skill-based-architecture

Skill-Based Architecture

Restructure oversized single-file Skills or scattered project rules into a well-organized Skill directory. Builds on the official minimal Agent Skill contract (name + description) and kicks in when a single small SKILL.md is no longer enough.

When to Use

• A single SKILL.md exceeds ~150 lines, mixing rules, workflows, and background material
• Project rules are scattered across AGENTS.md, CLAUDE.md, CODEX.md, .cursor/rules/, .claude/, etc.
• User explicitly requests Skill-based architecture or rule consolidation

When NOT to Use

• Very small projects (fewer than 3 rule/doc files)
• Temporary repos with no long-term maintenance needs
• Teams with a well-functioning documentation system who don't want to migrate

Progressive Rigor

Grow only under pressure. Tiers: Single-file (SKILL.md only, < 3 topics) → Folder-light (+ rules/, 3–5 topics or 1 recurring workflow) → Full (+ workflows/ + references/ + thin shells; ≥ 3 routed tasks, gotcha log, or multi-harness repo). Upgrade triggers: SKILL.md body > 90 lines or description > 25 lines, same pitfall surfaces twice, a task needs step-by-step instructions, or two harnesses share routing. Downgrade when content shrinks. Details: references/progressive-rigor.md.

Target Structure

skills/<name>/
├── SKILL.md          # dual budget (description ≤ 25 + body ≤ 90 lines): always-read list, task routing, priority
├── rules/            # Long-lived constraints (what is always true)
├── workflows/        # Step-by-step procedures (how to do a task)
├── references/       # Background: architecture, pitfalls, indexes
│   └── gotchas.md    # Recommended: known gotchas / footguns (most valuable reference)
└── docs/             # Optional: prompts, reports, external-facing material

Root entries (AGENTS.md, CLAUDE.md, CODEX.md, GEMINI.md, .cursor/rules/*.mdc) → thin shells with a routing.yaml bootstrap, not duplicated route tables. .cursor/skills/<name>/SKILL.md → Cursor registration entry (required for discovery). See REFERENCE.md for templates.

Core Principles

1. Single concise entry — SKILL.md keeps a dual budget: description ≤ 25 lines (trigger phrases + activation) + body ≤ 90 lines (navigation). It navigates, not exhausts. ✓ Check: smoke-test reports both separately; over either → split intent clusters / move detail to sub-files.
2. One skill folder — all formal docs under skills/<name>/, not scattered at repo root. ✓ Check: ls *.md at root shows only thin shells, not rule/workflow files.
3. Rules ≠ Flows — rules/ for constraints, workflows/ for procedures. ✓ Check: any numbered steps in rules/? Any "always/never" in workflows/? Either = mixing.
4. Routing.yaml as source — task routes live in routing.yaml; shells only say how to read it. ✓ Check: route changed without running sync/check? No → drift risk.
5. Cursor registration entry — .cursor/skills/<name>/SKILL.md must exist. ✓ Check: ls .cursor/skills/ — missing = Cursor cannot discover the skill.
6. Progressive Rigor — three tiers (Single-file / Folder-light / Full); grow only under pressure — see Progressive Rigor section above + details. ✓ Check: can you name the specific pressure that forced the current tier? "It felt right" ≠ pressure.
7. Description = coarse activation — domain boundary + real user trigger phrases; never enumerate workflow keywords nor summarize a workflow's steps — a step-summary becomes a shortcut the agent runs instead of reading the body (ref). ✓ Check: (a) can Common Tasks change without rewriting the description? (b) does the description or any route label carry HOW an agent could act on without opening the body/workflow? "no" to (a) or "yes" to (b) → fix.
8. Gotchas are highest-value — maintain costly pitfalls actively; keep them discoverable. ✓ Check: is each high-cost gotcha reachable from a Common Tasks route, not only buried in references/?
9. Progressive disclosure — SKILL.md links one level deep; deep content pulled only when task-routed. ✓ Check: open SKILL.md and follow every link — does any target file link further to a third level that should have been reachable from SKILL.md directly? If yes, SKILL.md is hiding its routing structure.
10. Task Closure Protocol — when a task modifies code or docs, finalization includes original-constraint check + AAR per the Trigger Policy, not just "tests passed" (ref); behavior change covers interaction, schema/renderer, styling, overlay/z-index, and host-compat. Pure Q&A / read-only tasks are exempt. ✓ Check: when the policy admitted the task into the protocol, can you restate the user's original constraints and all AAR answers before marking done?
11. Generalization rule — records must make sense outside current project context (ref). ✓ Check: replace project name with a different one — still makes sense? No → rewrite as pattern.
12. Self-maintenance — line counts signal evaluation, not automatic action. ✓ Check before splitting: topics independently navigable? Reader ever wants only one part? Both yes → split.
13. Activation over storage — pitfall in references/ alone is not "captured"; must also be on the task path. ✓ Check: trace normal route for this scenario — Agent hits the entry without hunting? No → stored, not activated.
14. Token efficiency — Always-read stays 2–3 files; domain files via Common Tasks only. ✓ Check: Always Read > 3 entries? Demote lowest-frequency.
15. Rationalizations Table — captures verbatim excuses from real pressure-test failures, organic or proven by a baseline run before shipping (ref, Phase 9). ✓ Check: every row traces to a real failure — no failure observed and unwilling to baseline it → imagined-pain, drop it.
16. Response discipline — output short, precise, direct answers; avoid process narration, self-congratulation, gratuitous confirmations, and requirement restatement. Correct objective errors neutrally; do not infer user stance. ✓ Check: does each sentence serve the explicit request? No → delete it.

Common Pitfalls

1. Missing Cursor registration entry — Formal skill at skills/<name>/ but no .cursor/skills/<name>/SKILL.md → Cursor never discovers the skill; all rules/workflows silently ignored
2. Soft-pointer-only shell — Thin shell says only "go read SKILL.md" without a routing.yaml bootstrap → instruction lost after context summarization in long conversations
3. Vague / wrong-scope description — Description is passive, wrong-language, too narrow ("fix bug" only), or bloated with every workflow keyword → skill misses natural requests or over-fires; keep description domain-level and route tasks in SKILL.md
4. Stored but not activated — Costly pitfall recorded in references/ but not surfaced in any workflow checklist or SKILL.md routing → future agents still miss it
5. Task Closure Protocol skipped when it should have fired — Agent considers itself "done" after main work and skips the 30-second AAR scan even though the Trigger Policy admitted the task (code/doc change happened) → lessons not captured. AAR is a completion gate when triggered, not an optional add-on. Pure Q&A / read-only tasks are correctly exempt — do not run AAR on them either
6. Project-specific records — Lessons written as project narratives ("in our product module, we found…") instead of reusable knowledge → useless outside current context; apply generalization rule before recording
7. No SessionStart hook on long sessions — /clear or /compact silently drops SKILL.md from context; agent loses all routing and protocol awareness without the user noticing → install SessionStart hook if your harness supports it (see references/thin-shells.md § SessionStart Hook)
8. Route skipping in multi-task sessions — Agent reads SKILL.md for the first task, then skips re-reading for subsequent tasks in the same session ("I already know the rules"). New tasks may match different routes; context may have been compressed. Result: agent works from partial/stale memory, misses critical rules, debugs in wrong direction for hours → SKILL.md template ships a tiered Session Discipline (re-match the route every task; re-read files only on route-change or compaction — cheap re-match catches different routes without re-reading everything); all shells carry the trigger
9. Long-task final drift — Agent follows the route early, then invents at the end after many tool calls or corrections → run templates/protocol-blocks/reboot-check.md before final validation/commit if original constraints are no longer fresh
10. Imagined-pain engineering — Agent 提议加任何机制(规则/脚本/文件结构/模板章节)前没反问"这解决的是真痛点还是脑补":为未发生的失败加保险、为想象用户预建脚手架、为不存在的协议加 marker / 监控、给假设的"agent 偏差"立规矩。✓ Check:能给一个具体场景(file+line / commit / session)证明这事真发生过吗?给不出 → 不上。Historic: 5 ghost scripts (砍 2026-05-19), dossier schema (砍 2026-05-19), reflection-first mode shift (弃 2026-05-20), observations 日志 (拒上 2026-05-20)

Content Classification

Content type	Target
Stable constraints, must-follow rules	rules/
Step-by-step task procedures	workflows/
Architecture, pitfalls, source indexes	references/
Known gotchas, footguns, edge cases	references/gotchas.md (or domain-specific pitfall files)
Prompts, reports, external docs	docs/
Editor/tool-specific config	.cursor/ / .claude/ (thin shells)

Multi-Skill & Composition

Multi-skill repos — see references/multi-skill-routing.md (operating + fission + coexistence). For invoking other skills from your workflows (embedded / serial / subagent delegation), see references/skill-composition.md + starter templates/skill/workflows/invoke-skill.md.example.

Resources

• WORKFLOW.md — Migration procedure (Quick Start + 9 phases + Downstream Upgrade)
• REFERENCE.md + references/ — Templates, decision guides, anti-patterns, troubleshooting, self-hosting routing source
• TEMPLATES-GUIDE.md — Starter templates + meta-workflow templates
• EXAMPLES.md + examples/ — behavior failures + before/after scenarios