Skill Based Architecture
A meta-skill that produces skills. Point it at any codebase and it distills the project's rules, workflows, and hard-won lessons into a dedicated skills/<name>/ directory — a project skill that becomes the single source of truth every AI agent (Cursor, Claude Code, Codex, Windsurf, Gemini) consults before every task.
WoJiSama · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add WoJiSama/skill-based-architectureAbout this skill
name: skill-based-architecture description: > This skill should be used when the user asks to "organize the project rules", "clean up scattered documentation", "把规则迁移到 skills 目录", "优化 skill 路由", "提高 description 命中率", or "减少薄壳重复维护". Activate when a SKILL.md is too large, rules are duplicated across agent entry files, task routing or trigger_examples miss natural user language, or templates / thin shells / validation scripts need drift-resistant maintenance.
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
- Temporary repos with no durable instruction or task-routing need
- Teams with a working documentation system that do not want to migrate
- Do not force structured folders onto a small project; an explicit SBA request
may still materialize a complete direct
SKILL.mdcarrier
Progressive Rigor
Grow only under pressure. The materializer derives Single-file,
Folder-light, or Full/broad internally from target evidence; users do
not select a tier, profile, capability pack, or install mode. routing.yaml,
Task Execution, Task Closure, maintenance checks, and each harness surface need
their own routing/loading/ownership pressure. Split by abstraction (骨架/肉)
when content tangles invariant design theory with current-code facts: abstract
theory → architecture/, code maps → references/, house style →
conventions/, per-module landmines → gotchas/ (methodology stays in
rules/). Downgrade when content shrinks. Details:
references/progressive-rigor.md.
Evidence-Selected Structure
# direct
skills/<name>/SKILL.md
# folder-light or broad: only admitted owners/directories
skills/<name>/{SKILL.md,rules/,workflows/,references/,scripts/}
# routing.yaml appears only when route data has an independent owner
# root/tool entry and registration surfaces appear only for proven readers
Existing root entries are preserved. Emitted routed entries use a generated
routing.yaml bootstrap; direct entries point to the sole SKILL.md procedure.
Cursor registration exists only when Cursor is detected, declared, currently
used, or explicitly requested. See REFERENCE.md for sources.
Core Principles
- Single concise entry —
SKILL.mdkeeps 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. - One skill folder when a folder is admitted — folder-light and broad results keep formal docs under
skills/<name>/; a direct result may remain a complete singleSKILL.mdcarrier. ✓ Check: no emitted root entry becomes a second rule/workflow owner. - Rules ≠ Flows —
rules/for constraints,workflows/for procedures. ✓ Check: any numbered steps inrules/? Any "always/never" inworkflows/? Either = mixing. - Routing.yaml as source when admitted — a direct carrier owns its sole
route in
SKILL.md; multiple/shared routes live only inrouting.yaml, with routed shells generated from it. ✓ Check: is there an independent selector or consumer that justifies the manifest, and does its fitted sync check pass? - Harness surfaces follow readers — create/merge only entries and registrations supported by existing files/config, the current harness, repository/team declaration, or an explicit request. ✓ Check: can every emitted surface name its reader, and was every existing entry preserved?
- Progressive Rigor — three carriers (Single-file / Folder-light / Full) grow only under pressure and are not user package choices. ✓ Check: can you name the independent responsibility that forced every generated file?
- 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
routing.yamltask routes 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. - Gotchas are highest-value — maintain costly pitfalls actively; keep them discoverable. ✓ Check: is each high-cost gotcha activated by the admitted route owner (
SKILL.mdorrouting.yaml), not only buried inreferences/? - Progressive disclosure — every loaded file needs an independent task-time reason; conditional content leaves the startup read set, and files every real caller co-loads should merge unless ownership/generation requires separate storage. ✓ Check: for each route read, can you name a request that needs it now and a next action it changes? No → conditionally route, merge, or remove it.
- Task Execution + Closure — after route selection, only one clear read-only or fixed-contract maintenance action/check with no new desired behavior executes directly. Any request that adds or changes user-visible behavior, a business flow/state, or an external contract follows
requirement-ready -> Task Anchor -> implementation-ready -> Native Plan -> mutation: an incomplete Requirement returns understanding, real risk/conflict, and the minimum normative question; a clear one needs no ceremonial confirmation