SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsintent-layer

intent-layer

Coding & development

View repository

Updated 10-16 04:57

About this skill

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)

  1. Measure [gate - show table first] scripts/analyze_structure.sh /path/to/project scripts/estimate_tokens.sh /path/to/each/source/dir

  2. Decide No root file → Ask: CLAUDE.md or AGENTS.md? Has root file → Add Intent Layer section + child nodes if needed

  3. 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

  4. 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

## Attribution

This skill is vendored from [crafter-station/skills](https://github.com/crafter-station/skills/tree/main/context-engineering/intent-layer) (MIT, © 2026 Crafter Station). See `LICENSE` in this directory.

Built by [Railly Hugo](https://railly.dev) for [Crafter Station](https://crafterstation.com), based on [The Intent Layer](https://www.intent-systems.com/learn/intent-layer) by Tyler Brandt.