skill-based-architecture

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