Skill-Based Architecture
English | 中文
A lifecycle framework for AI-agent rule systems. Turns scattered prompt documents (AGENTS.md, CLAUDE.md, .cursor/rules/, README rules) into routable, verifiable, updatable engineering assets under skills/<name>/.
It focuses on the rule system itself: structure, routing, workflows, validation, after-action learning, and upstream/downstream updates. It does not ship technology-specific rules — those belong in your downstream project skill.
Install
Claude Code — one line:
/plugin marketplace add WoJiSama/skill-based-architecture
/plugin install skill-based-architecture@skill-based-architecture
Then trigger it; pull updates later with /plugin marketplace update.
Cursor / Codex / Gemini / other harnesses don't share Claude Code's plugin system — clone the repo instead (see Quick Start).
What it produces
scattered project guidance
AGENTS.md / CLAUDE.md / .cursor/rules / README notes
│
▼
skills/<project>/
├── SKILL.md # router: description ≤ 25 + body ≤ 90 lines (dual budget)
├── rules/ # stable constraints
├── workflows/ # repeatable procedures
├── references/ # architecture, gotchas, indexes
└── docs/ # optional reports and prompts
tool entry files
AGENTS.md / CLAUDE.md / CODEX.md / GEMINI.md / .cursor/rules / .codex
└── thin shells: route to skills/<project>/, no duplicated rule bodies
Why
| Symptom | What goes wrong |
|---|
Single SKILL.md with 400+ lines | Agent reads everything every task — wastes tokens, hides what matters |
Rules duplicated across AGENTS.md, .cursor/rules/, CLAUDE.md | Drift, contradictions, no source of truth |
| Skill activation is unreliable | Description is a passive summary instead of explicit trigger conditions |
| Hard-won lessons buried in docs | Costly pitfalls never surface during the next task |
| Rule files only grow, never shrink | Useful rules get buried by obsolete ones |
The architecture answers each: a routing source-of-truth (routing.yaml), thin shells everywhere else, description-as-trigger discipline, AAR with a recording threshold, and self-maintenance via line-count signals + split/merge procedures.
When NOT to use
- Total rule content < 50 lines (a single
CLAUDE.md is enough)
- Single harness, no team sharing, no recurring tasks
- Short-lived solo project (< 2 weeks)
Start with a plain CLAUDE.md or .cursor/rules/workflow.mdc; upgrade later when content sprawls. WORKFLOW.md has a Quick Start path for that upgrade.
Quick Start
1. Make this meta-skill available locally
Claude Code: already done via the one-line install above — skip to step 2.
Cursor / Codex / Gemini / other harnesses: pull this repo any way you want (git clone, download zip, submodule, fork…) to any location — the only requirement is that you and the agent both know where it lives.
As long as the agent can locate this directory when triggered, the path doesn't matter. If it isn't on the agent's default search path (e.g., Cursor's ~/.cursor/skills/, .cursor/skills/, or the project's own skills/), write the path into CLAUDE.md / AGENTS.md / .cursor/rules/ so the agent can find it.
Common placements:
- Inside the project:
skills/skill-based-architecture/
- Next to the project:
../skill-based-architecture/
- Cursor user-level:
~/.cursor/skills/skill-based-architecture/
- Cursor project-level:
.cursor/skills/skill-based-architecture/
Example (clone inside the project):
git clone https://github.com/WoJiSama/skill-based-architecture.git \
skills/skill-based-architecture
2. Trigger it from the target project
Ask the agent to use the local meta-skill:
"Use skill-based-architecture to refactor the project rules"
Equivalent triggers: "Organize the project rules", "Migrate rules to skills/", "整理项目规则".
