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.

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

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

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.

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

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

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/", "整理项目规则".

The agent then copies the pre-built scaffold from templates/ into skills/<name>/, creates the thin shells, fills every <!-- FILL: --> marker, and runs validation. Full procedure: WORKFLOW.md.

Several workflows in this meta-skill lean on sub-agent delegation and parallel agent fan-out (see templates/skill/workflows/subagent-driven.md and templates/skill/workflows/refactor-fanout.md). In most harnesses the in-repo rules are enough — the agent decides on its own when to fan out.

Codex is the exception. Its runtime imposes a tool-level rule on spawn_agent: it may only be invoked when the user explicitly asks for sub-agent, delegation, or parallel agent work. That tool-level rule outranks anything in this repo's AGENTS.md or skill files, so the fan-out patterns will not fire automatically — even though the workflow documents tell the agent to use them.

If you're in Codex and want sub-agent work to actually happen — fan-out or anything else — you have to authorize it explicitly. Two equivalent patterns:

Per-task — name the specific work you want delegated:

"Use a sub-agent to refactor the rule files." "Spawn sub-agents to review each workflow file in parallel." "请使用 sub-agent 来扫一遍 templates 目录。"

Session-wide — grant blanket permission once at the start:

"In this session you may use sub-agents whenever the workflow calls for it." "本次会话我允许你使用 sub-agent。" "Feel free to delegate to sub-agents in this session."

Either form satisfies the tool-level rule. Without one of them, Codex will silently skip the delegation step — even when the workflow documents tell the agent to use sub-agents.

• Two-layer routing. SKILL.md keeps a short generated Always Read list; Common Tasks routes the agent to extra files only when needed. routing.yaml is the editable source of truth in downstream projects.
• Thin shells with routing bootstrap. Every entry file embeds a short bootstrap that points to routing.yaml. The route table is not duplicated across shells; natural-language-only instructions get lost during context summarization.
• Description as trigger condition. Domain-level activation phrases in the user's actual language(s), not workflow keyword stuffing. Re-read aloud after edits — no script substitutes for hearing whether it sounds like a real user.
• Session Discipline + Task Closure. Re-match the route on every new task; re-read files only when the route changed or context was compacted; finish non-trivial tasks with a 30-second AAR scan + recording threshold, never "tests passed = done".
• Self-maintenance. Line-count signals trigger evaluation, not automatic action; split/merge procedures and freshness checks keep docs lean.
• Cross-harness. Compatible with Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, and AGENTS.md-based tools.

All entries must contain a routing.yaml bootstrap — for Claude Code native skills, prefer project-specific names (<project>-review) since enterprise > personal > project precedence resolves same-name skills.

Per-tool templates: references/per-tool-shells.md. Tool compatibility deep dive: same file.

Does this replace the official Anthropic skill template? No. The official template defines the minimal skill shape (a folder with SKILL.md + frontmatter). This meta-skill starts one level later — it adds structure when a single small SKILL.md is no longer enough.

Can I migrate incrementally? Yes. Round 1: extract rules. Round 2: extract workflows. Round 3: extract references and create thin shells. Each round leaves the project in a working state.

How do downstream projects receive upstream improvements? Ask the agent to update from upstream. The copied workflows/update-upstream.md clones the latest upstream, reads UPSTREAM-CHANGES.md from the cloned repo, compares files itself, patches in mechanism changes, preserves project-owned content, and re-runs validation including conformance against upstream's own contract.

Learn AI on LinuxDO — LinuxDO