skill-based-architecture

Most coding agents can read a rules file. Real repositories ask for more: rules are scattered across tool entry files, business meaning is not identical to current code, the right context changes by task, and a successful command is often only an intermediate state.

SBA gives the Agent a project-level operating contract. The Agent inventories the repository, selects one workflow, loads only evidence that can change the next decision, binds desired meaning to the current code owner, verifies the requested result, and records proven learning only when it will change a future action. Ordinary users keep the decisions that truly belong to them: product meaning, business rules, permissions, and high-cost tradeoffs.

What Changes

Without SBA	With SBA
The same rule is copied across AGENTS.md, CLAUDE.md, Cursor rules, and README notes	Complete meaning has one owner; tool entry files keep only the local hook needed to reach it
Every task loads one large instruction file	One task route selects one workflow; later knowledge is pulled only when an unresolved decision needs it
The Agent guesses implementation scope from request keywords	User-confirmed meaning and repository evidence are translated into the current code owner and an executable change contract
A command, commit, or push is treated as "done"	Completion is checked against the current task's bound deliverables and exact requested terminal state
Lessons accumulate as passive documentation	A proven, reusable failure is reconciled into the right owner and connected to the next task that needs it

When It Fits

Use SBA when one or more of these pressures are real:

• project instructions are duplicated or contradictory across agent entry files;
• a single SKILL.md has become hard to navigate;
• recurring tasks need procedures, fitted verification, or reliable completion checks;
• costly failures keep being rediscovered because the lesson is stored but never activated;
• several harnesses need the same project knowledge without maintaining several rule systems.

Small projects should stay small. Quick Start now derives a direct, folder, or broad downstream shape from the target repository's evidence. A full migration workflow remains available when the admitted work needs deeper analysis; ordinary users do not select tiers, profiles, capability packs, or installation modes.

SBA is usually unnecessary for a temporary repository, a project with fewer than three small rule/document files, or a team that already has a compact, reliable instruction system and does not want to migrate. See Progressive Rigor for the growth model.

Quick Start

1. Make SBA available to your Agent

Claude Code: install with two commands.

/plugin marketplace add WoJiSama/skill-based-architecture
/plugin install skill-based-architecture@skill-based-architecture

Use /plugin marketplace update when you want the latest marketplace version.

Cursor, Codex, Gemini, Windsurf, OpenCode, or another file-aware harness: clone it next to the target project.

git clone https://github.com/WoJiSama/skill-based-architecture.git \
  ../skill-based-architecture

The exact location is not part of the product contract. The Agent only needs read access and an explicit path when its harness does not discover the Skill automatically. Tool-specific entry options live in Per-tool shells.

2. Ask for the result in ordinary language

With the plugin installed:

Use skill-based-architecture to organize this project's rules.

With a local clone:

Read ../skill-based-architecture/SKILL.md, then use it to organize this project's rules.

Equivalent requests such as "organize the project rules", "migrate rules to skills", or "把规则迁移到 skills 目录" route to the same migration workflow.

From that request, the Agent owns the engineering work:

1. inventory existing instruction entries and inspect the smallest repository evidence needed to understand the project;
2. calibrate user-confirmed product or business meaning, while keeping it distinct from current implementation facts;
3. derive the evidence-selected physical shape and admitted owners (direct, folder, or broad), then enter the full migration workflow only when the evidence requires deeper analysis;
4. preview every create, preserve, and conflict decision before writing, then apply and semantically merge preserved instructions;
5. verify both the generated structure and the source-to-destination evidence for the migrated meaning.

You should only be asked about a real product or business choice, an authority boundary, or a high-cost tradeoff that repository evidence cannot decide.

Current materialization boundary: scaffold-downstream.sh inventories the target, derives an evidence-selected direct, folder, or broad result, and creates only the Skill owners, routes, checks, and harness surfaces admitted by that evidence. It does not expose a tier/profile/capability/install-mode switch. The Agent still owns project-content filling, preserved-entry merging, and source-to-destination semantic evidence before migration is complete.

Try it without a private repository

• Use examples/simple-repo/ as a tiny local fixture with deliberately duplicated instructions.
• Use COPY-PASTE-INPUT.md when a hosted environment accepts pasted files.
• Run SBA in Telegram or WhatsApp through ClawMama for a lightweight external preview. Do not upload sensitive project rules.

The fixture proves the basic migration and routing behavior. It is intentionally small and is not a showcase of the maximum depth of a real repository migration.

How One Real Task Flows

flowchart LR
    A["User request"] --> B["Select one workflow"]
    B --> C["Load decision-relevant evidence"]
    C --> D["Bind desired meaning to the current code owner"]
    D --> E["Implement"]
    E --> F["Verify risk and requested end state"]
    F -->|"Evidence fails or premise changes"| C
    F -->|"Verified"| G["Record reusable learning when justified"]
    G --> H["Deliver the requested artifact"]

This is a result-oriented lifecycle, not a fixed ceremony. Simple and read-only tasks skip stages that do not apply. When evidence invalidates the current premise, the Agent returns to localization or decomposition instead of preserving the appearance of linear progress.

The Reliability Contract

Capability	What SBA expects from the Agent
See enough information	Distinguish user intent, business meaning, architecture contracts, code facts, runtime evidence, and historical conclusions; stop reading when the current decision is resolved
Judge without a standard answer	Make tradeoffs explicit, compare real alternatives, request only the smallest missing normative decision, and replan when evidence changes
Coordinate reliable execution	Give workflows, tools, and optional workers clear scope, inputs, outputs, forbidden areas, and review evidence while the main Agent retains final responsibility
Finish the exact request	Prove only the deliverables and terminal states bound by the current request and governing Requirement as projected into the Task Anchor; Plans only identify and order technical delivery for those already-bound artifacts

These are product principles, not claims that a longer checklist is always better. The full decision boundary is in the SBA Bible.

Proof, Not Promises

Boundary	Current safeguard
Before writing	The scaffold defaults to a read-only preview and reports every CREATE, PRESERVE, and CONFLICT decision
Existing project truth	Existing entry files are preserved byte-for-byte until the Agent performs an evidence-backed semantic merge
Failed apply	Work is staged first; newly created paths are rolled back when scaffold apply fails
Structural integrity	SKILL.md is always checked; routing, shells, workflows, Cursor, links, reachability, orphan, budgets, and content contracts are strict only for responsibilities actually materialized
Migration integrity	Every inventoried source clause needs one mapped/excluded disposition; verbatim mappings and activation chains are executable checks, while faithful rewrites retain explicit semantic-review evidence
Behavior integrity	Deterministic green never claims model behavior; separate opt-in live Codex journeys test a fresh-project Single-file task and ordinary SBA migration, and report external unavailability separately
Delivery integrity	A local change is not a commit, a commit is not a push, a pushed branch is not an MR or PR, and an approved MR or PR is not a merge

Structural checks do not prove that every previous instruction survived semantically. The migration-evidence gate can prove inventory coverage, verbatim preservation, and activation-chain integrity, but a faithful rewrite still depends on its recorded semantic review. Live Agent behavior is another independent proof layer. SBA keeps these claims separate instead of letting one green aggregate replace judgment.

UPSTREAM="${UPSTREAM:-../skill-based-architecture}"
NAME="<project-name>"
SUMMARY="<one-line project summary>"

# Read-only path preview.
bash "$UPSTREAM/scripts/scaffold-downstream.sh" \
  --target "$PWD" --name "$NAME" --summary "$SUMMARY"

# Apply after the Agent has reviewed the inventory and project evidence.
bash "$UPSTREAM/scripts/scaffold-downstream.sh" \
  --target "$PWD" --name "$NAME" --summary "$SUMMARY" --apply

# Run only the fitted checks that the materializer emitted.
if [[ -f "skills/$NAME/scripts/smoke-test.sh" ]]; then
  bash "skills/$NAME/scripts/smoke-test.sh" "$NAME"
fi
if [[ -f "skills/$NAME/routing.yaml" && -f "skills/$NAME/scripts/sync-routing.sh" ]]; then
  bash "skills/$NAME/scripts/sync-routing.sh" "$NAME" --check
fi
for check in audit-orphans route-reachability route-health; do
  if [[ -f "skills/$NAME/scripts/$check.sh" ]]; then
    (cd "skills/$NAME" && bash "scripts/$check.sh")
  fi
done