mcpField
I
intent-layer

intent-layer

github.com/crafter-stationAgent workflows113629 installsUpdated 8w ago
Repository

About intent-layer

Intent Layer is a skill for organizing hierarchical AGENTS.md files so coding agents can navigate a codebase using focused context. It includes scripts to inspect setup state, identify structural boundaries, and estimate directory complexity.

Key features

  1. 01Detect existing context-file state
  2. 02Analyze semantic code boundaries
  3. 03Estimate directory token complexity
  4. 04Provide root and child file templates
  5. 05Guide capture of ownership and invariants

Use cases

  1. 01Set up AGENTS.md context in a codebase
  2. 02Add guidance for complex subsystems
  3. 03Document invariants and recurring engineering pitfalls

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/crafter-station/skills --skill intent-layer

After installing, type/intent-layerin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

README.md
references/
capture-protocol.md
node-examples.md
templates.md
scripts/
analyze_structure.sh
detect_state.sh
estimate_tokens.sh

Details

From the project README

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

SignalAction
>20k tokens in directoryCreate AGENTS.md
Responsibility shiftCreate AGENTS.md
Hidden contracts/invariantsDocument in nearest ancestor
Cross-cutting concernPlace 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

Comments

Markdown supported