AGENTS.md

1# .agents/skills — Agent Contract
2 
3## Scope
4 
5This subtree owns runtime skill discovery files for harnesses that read
6`.agents/skills` directly or through generated adapters.
7 
8## Contract
9 
10Flat `.md` files and `<name>/SKILL.md` directories are adapter/runtime surfaces.
11They must route to the same canonical skill behavior described in
12`docs/reference/skills.md` and `prompts/skills`.
13 
14## Dependencies
15 
16Use `sdp.manifest.yaml`, `docs/reference/skills.md`, and
17`docs/reference/skill-authoring.md` as the normalization sources. Do not invent a
18third skill taxonomy here.
19 
20## Runtime Assumptions
21 
22Different harnesses read different shapes:
23 
24- OpenCode, Cursor, and Kimi can read flat `.md` files.
25- Pi-compatible loaders need `<name>/SKILL.md` directories.
26- Codex-style runtimes may rely on explicit paths from root instructions.
27 
28## Local Rules
29 
30- Deprecated aliases must redirect to the canonical intent or replacement skill.
31- Intent skills must not diverge from published structured skills.
32- If a runtime file is only an adapter, keep it thin and point to the canonical
33  owner.
34- Runtime skills must preserve completion discipline from canonical skills:
35  scoped staging, commit, push or exact blocker. Never add `git add .` to skill
36  instructions.
37- Keep `README.md` aligned with the actual filesystem and manifest state.
38