intent-layer — Claude Code skill: hierarchical AGENTS.md setup
Builds a folder-by-folder context tree — one root AGENTS.md plus child nodes — so agents read your codebase the way a senior engineer would.
npx skills add crafter-station/skills --skill intent-layer -a claude-codeWhat intent-layer does
The skill sets up a hierarchical Intent Layer made of AGENTS.md files. There is exactly one root context file; child AGENTS.md files go into subsystems that need their own explanation. CLAUDE.md and AGENTS.md should not sit together at the project root, and that rule is where most existing repos break.
The workflow is scripted. scripts/detect_state.sh reports whether the layer is none, partial or complete. Then scripts/analyze_structure.sh finds semantic boundaries and scripts/estimate_tokens.sh measures how heavy each source directory is. A child node earns its place past 20k tokens or when responsibility shifts. Simple utilities and test folders usually do not need one.
Structure comes from references/templates.md, real patterns from references/node-examples.md, and interview questions from references/capture-protocol.md. Keep every node under 4k tokens and give it a READ-FIRST directive. Once the state reads complete, the skill switches to maintenance: audit existing nodes, hunt for new candidates, or both.
What it helps with
- split project context across folders instead of one long file
- teach an agent where one subsystem ends and another begins
- record invariants that must never be broken
- spot directories that need their own AGENTS.md
- audit context nodes that already exist
Example prompts for the agent
- set up an intent layer for this project
- add an AGENTS.md for the src/payments folder
- check the intent layer state and suggest new nodes
How to install intent-layer
1Skills CLI (Vercel)
npx skills add crafter-station/skills --skill intent-layer -a claude-code2Manually: put the files in place
~/.claude/skills/intent-layer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/intent-layer/
1Skills CLI (Vercel)
npx skills add crafter-station/skills --skill intent-layer -a codex2Manually: put the files in place
.agents/skills/intent-layer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add crafter-station/skills --skill intent-layer -a cursor2Manually: put the files in place
.cursor/skills/intent-layer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install crafter-station/skills intent-layer2Manually: put the files in place
.github/skills/intent-layer/SKILL.md1Skills CLI (Vercel)
npx skills add crafter-station/skills --skill intent-layer -a gemini-cli2Platform CLI
gemini skills install https://github.com/crafter-station/skills --path skills/intent-layerManually: put the files in place
.devin/skills/intent-layer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add crafter-station/skills --skill intent-layer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about intent-layer
How do I install intent-layer in Claude?
Run npx skills add crafter-station/skills --skill intent-layer -a claude-code. The skill file then lands at ~/.claude/skills/intent-layer/SKILL.md.
What does intent-layer do?
It builds an AGENTS.md hierarchy: one root file plus child nodes in subdirectories. It also inspects an existing layer and proposes new nodes.
Can CLAUDE.md and AGENTS.md both live at the project root?
No. The root context file has to be a single source of truth, otherwise the agent gets two competing sets of instructions. Child AGENTS.md files in subdirectories are fine.
Source text
SKILL.md · MIT
--- name: intent-layer version: 1.0.0 description: > Set up hierarchical Intent Layer (AGENTS.md files) for codebases. Use when initializing a new project, adding context infrastructure to an existing repo, user asks to set up AGENTS.md, add intent layer, make agents understand the codebase, or scaffolding AI-friendly project documentation. --- # Intent Layer Hierarchical AGENTS.md infrastructure so agents navigate codebases like senior engineers. ## Core Principle **Only ONE root context file.** CLAUDE.md and AGENTS.md should NOT coexist at project root. Child AGENTS.md in subdirectories are encouraged for complex subsystems. ## Workflow ``` 1. Detect state scripts/detect_state.sh /path/to/project → Returns: none | partial | complete 2. Route none/partial → Initial setup (steps 3-5) complete → Maintenance (step 6) 3. Measure [gate - show table first] scripts/analyze_structure.sh /path/to/project scripts/estimate_tokens.sh /path/to/each/source/dir 4. Decide No root file → Ask: CLAUDE.md or AGENTS.md? Has root file → Add Intent Layer section + child nodes if needed 5. Execute Use references/templates.md for structure Use references/node-examples.md for real-world patterns Validate: one root, READ-FIRST directive, <4k tokens per node 6. Maintenance mode (when state=complete) Ask user: a) Audit nodes → Use references/capture-protocol.md for SME questions b) Find candidates → Re-measure tokens, suggest new nodes c) Both ``` ## When to Create Child Nodes | Signal | Action | |--------|--------| | >20k tokens in directory | Create AGENTS.md | | Responsibility shift | Create AGENTS.md | | Hidden contracts/invariants | Document in nearest ancestor | | Cross-cutting concern | Place at LCA | Do NOT create for: every directory, simple utilities, test folders (unless complex). ## Capture Questions When documenting existing code, ask: 1. What does this area own? What's out of scope? 2. What invariants must never be violated? 3. What repeatedly confuses new engineers? 4. What patterns should always be followed? ## Resources **Scripts:** - `scripts/detect_state.sh` - Check Intent Layer state (none/partial/complete) - `scripts/analyze_structure.sh` - Find semantic boundaries - `scripts/estimate_tokens.sh` - Measure directory complexity **References:** - `references/templates.md` - Root and child node templates - `references/node-examples.md` - Real-world examples - `references/capture-protocol.md` - SME interview protocol
© crafter-station · MIT · crafter-station/skills
