agent-instruction-writer
Skill1 starsChanged 5 months agoMITView on GitHub
Write project-level instructions for coding agents and AI agents, including CLAUDE.md, AGENTS.md, Cursor rules, Codex instructions, and repository-specific agent behavior policies. Use this skill when a user wants an AI agent to work safely and consistently inside a codebase or workflow.
In this repository9 other files it gives its agents.
- prompt-xray-skillsSkill
- prompt-brief-builderSkill
- prompt-auditorSkill
- system-prompt-architectSkill
- rag-answer-policySkill
- structured-output-designerSkill
- prompt-test-generatorSkill
- prompt-debuggerSkill
- prompt-to-product-specSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 11 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Use this skill to create project-level instructions for AI agents.
- Distinctive: line 18
Use this skill when the user wants to create or improve:
- Distinctive: line 43
If information is missing, mark placeholders instead of inventing details.
- Distinctive: line 58
If unknown, write platform-neutral instructions.
- Distinctive: line 94
ask for clarification when scope is unclear.
- Distinctive: line 105
add dependencies without justification.
- Distinctive: line 113
Read relevant files first.
- Distinctive: line 116
Run or describe relevant checks.
- Distinctive: line 130
If commands are unknown, use placeholders.
- Distinctive: line 136
when tests are required;
- Distinctive: line 243
do-not-touch zones are clear.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Agent Instruction Writer Skill
Purpose
Use this skill to create project-level instructions for AI agents.
The goal is to reduce agent drift, accidental rewrites, broken architecture, unsafe assumptions, and low-quality changes.
Good agent instructions are not motivational. They are operational rules for how the agent should work inside a specific project.
When to use
Use this skill when the user wants to create or improve:
CLAUDE.md;AGENTS.md;- Cursor project rules;
- Codex instructions;
- coding-agent guidelines;
- repository-specific AI instructions;
- AI workflow rules for product, content, research, or support agents.
Required input
Collect or infer:
- project purpose;
- tech stack;
- architecture overview;
- important directories;
- commands for install, dev, test, lint, build;
- do-not-touch zones;
- coding conventions;
- testing expectations;
- output/reporting format;
- known fragile areas.
If information is missing, mark placeholders instead of inventing details.
Procedure
1. Identify the agent environment
Determine whether the instructions are for:
- Claude Code;
- Codex;
- Cursor;
- Aider;
- a custom agent;
- a general repository AI assistant.
If unknown, write platform-neutral instructions.
2. Define project context
Explain what the project does in 3-6 sentences.
Include:
- target users;
- business goal;
- main workflows;
- production risks.
3. Define architecture boundaries
List major directories and responsibilities.
Example:
app/ UI and routes
lib/ shared business logic
api/ server endpoints
workers/ background jobsTell the agent where changes should and should not happen.
4. Define allowed behavior
Specify what the agent may do:
- make small focused changes;
- preserve existing architecture;
- add tests;
- update docs;
- ask for clarification when scope is unclear;
- explain trade-offs.
5. Define forbidden behavior
Specify what the agent must not do:
- rewrite unrelated files;
- change public APIs without instruction;
- modify secrets or credentials;
- remove error handling;
- add dependencies without justification;
- replace architecture without approval;
- silently ignore failing tests.
6. Define workflow
A good coding agent should:
- Read relevant files first.
- Summarize the intended change.
- Make the smallest safe change.
- Run or describe relevant checks.
- Report what changed and what remains risky.
7. Define command policy
Include commands for:
- install;
- development;
- lint;
- typecheck;
- tests;
- build.
If commands are unknown, use placeholders.
8. Define testing policy
Specify:
- when tests are required;
- what to do if tests cannot be run;
- how to handle failing tests;
- whether snapshots, integration tests, or manual QA are expected.
9. Define reporting format
Require the agent to finish with:
- summary;
- files changed;
- checks run;
- risks;
- follow-up recommendations.
Output format
Return a ready-to-copy instruction file:
# Agent Instructions
## Project Overview
[Describe the project.]
## Tech Stack
- Runtime:
- Framework:
- Database:
- Auth:
- Deployment:
- Testing:
## Architecture Map
| Path | Responsibility |
|---|---|
| `...` | ... |
## Working Rules
The agent should:
- ...
The agent must not:
- ...
## Change Workflow
For every task:
1. Read relevant files before editing.
2. Identify the smallest safe change.
3. Preserve existing architecture unless explicitly asked to change it.
4. Update tests or explain why tests are not applicable.
5. Report changes clearly.
## Commands
```bash
# install
# development
# lint
# typecheck
# test
# buildTesting Policy
- ...
Risk Areas
- ...
Response Format
After completing a task, respond with:
## Summary
## Files Changed
## Checks Run
## Risks / Notes
## Suggested Next Steps
## Quality checklist
Before finalizing, verify:
- project context is specific;
- do-not-touch zones are clear;
- commands are present or marked as placeholders;
- reporting format is defined;
- forbidden behavior is concrete;
- the instructions reduce agent autonomy where risk is high.
## Boundaries
This skill writes agent instructions. It does not verify that a specific agent will always follow them. Test the instructions on real tasks and refine them based on observed failures.Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

