| name | setup-instructions |
| description | Set up the project instruction file (CLAUDE.md / AGENTS.md). Use when starting work on a new project that doesn't have an instruction file yet. Explores the codebase, drafts the instruction file, and asks the user to review and refine it. |
Set Up Instruction File
Creates a concise, high-signal instruction file for the project.
Initial Setup
Respond with:
I'll set up an instruction file for this project. First, let me explore the codebase to understand what's here.
Then immediately begin the workflow — do not wait for user input.
Workflow
- Explore the codebase — read project root files (package.json, pyproject.toml, Makefile, Cargo.toml, etc.), scan key directories, identify the tech stack, build/test/lint commands, and project structure
- Draft the instruction file using the template below — fill in every section based on what you found
- Present the draft to the user in chat — do NOT write the file yet. Show the full draft and ask:
Here's my draft. Before I write it, please review:
- **Correct** any misunderstandings — wrong commands, misidentified patterns, incorrect assumptions
- **Add** anything I missed — boundaries, team conventions, things you know that aren't in the code
- **Align** the file with how your team actually works — does this match your mental model of the project?
The goal is 15–30 lines of genuinely useful context. What should I change?
- Iterate — incorporate the user's feedback. If they say it looks good, proceed.
- Determine filename — check which skills directory exists (
.claude/, .cursor/, .github/, .codex/) to infer the tool. Use CLAUDE.md for Claude Code, AGENTS.md for everything else. Confirm with the user before writing.
- Write the file to the project root
Guidelines
- Think of this file as a contract between the team and the agent. It defines how the agent should work in this project — what to do, what not to touch, what patterns to follow.
- Including key patterns and conventions the agent could discover by reading code is fine — it saves tokens and avoids the agent re-discovering them in every new session.
- Do NOT include framework documentation the agent already knows or code style rules a linter enforces.
- DO include: build/test/lint commands, architectural boundaries, established patterns, conventions, and things to avoid.
- State rules positively ("Use X") except in the Boundaries section
Template
# [CLAUDE.md or AGENTS.md]
## Project
<!-- 1-3 sentences: What is this? What does it do? Tech stack? -->
## Commands
<!-- The commands useful for working with this codebase. Adapt to the stack — e.g. build, test, lint, run, type-check, etc. -->
## Architecture
<!-- Key directories and what they contain. Only non-obvious ones. -->
## Conventions
<!-- Only rules a linter CANNOT enforce. -->
## Boundaries
<!-- What the agent must NOT do. Be specific about why. -->
## Testing
<!-- How tests work in this project. What pattern to follow. -->