Skill-Based Architecture: one project Skill your coding agent routes through

What SBA solves, and the repositories it is built for

Skill-Based Architecture is a Skill, not an agent operating system, task database, or execution runtime. The README is explicit about that boundary, and it matters, because the name suggests more infrastructure than the project ships. What it actually does is produce a project Skill: a skills/<name>/ directory that holds the project's rules, workflows and lessons, so that Cursor, Claude Code, Codex, Windsurf and Gemini consult one owner instead of five drifting copies.

The problem it names is duplication and contradiction. The same rule gets copied across AGENTS.md, CLAUDE.md, Cursor rules and README notes. Every task then loads one large instruction file, and the agent guesses implementation scope from request keywords. The README's own comparison table frames the shift: complete meaning gets one owner, tool entry files keep only the local hook needed to reach it, and one task route selects one workflow.

The target user is a team running more than one harness against the same repository, or a team whose single SKILL.md has become hard to navigate. The README also names the cases where it is unnecessary: a temporary repository, a project with fewer than three small rule or document files, or a team that already has a compact, reliable instruction system and does not want to migrate. That last clause is unusual honesty for a tool README, and it is the right place to start your evaluation.

The mechanism: inventory, evidence-selected shape, preview, verify

The workflow is a sequence the agent owns after you ask in ordinary language. First it inventories existing instruction entries and inspects the smallest repository evidence needed to understand the project. Then it calibrates user-confirmed product or business meaning, keeping that distinct from current implementation facts. Then it derives the physical shape and admitted owners from evidence, choosing between direct, folder and broad. It previews every create, preserve and conflict decision before writing. Finally it verifies both the generated structure and the source-to-destination evidence for the migrated meaning.

The shape selection is the part worth understanding. Quick Start derives a direct, folder or broad downstream shape from the target repository's evidence, and the README says ordinary users do not select tiers, profiles, capability packs or installation modes. The scaffold-downstream.sh script is the materialization boundary: it inventories the target, derives the shape, and creates only the Skill owners, routes, checks and harness surfaces admitted by that evidence. The agent still owns project-content filling, preserved-entry merging, and source-to-destination semantic evidence.

Two design choices deserve scrutiny. The first is that the script deliberately exposes no tier or install-mode switch, which keeps the surface small but means you cannot force a heavier migration than the evidence supports. The second is the gate on user questions: 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. That is a narrow set, and it assumes the inventory step reads your repository well enough to decide the rest.

Installing SBA and producing your first project Skill

Claude Code installs through the plugin marketplace with two commands. The README gives them as text, not bash, because they are slash commands typed into the harness, not shell commands.

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

After that, `/plugin marketplace update` pulls the latest marketplace version. For Cursor, Codex, Gemini, Windsurf, OpenCode or another file-aware harness, the README's route is a clone next to the target project. The exact location is not part of the product contract; the agent needs read access and an explicit path when its harness does not discover the Skill automatically.

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

With the plugin installed, you ask in ordinary language: "Use skill-based-architecture to organize this project's rules." With a local clone, you point the agent at the file first: "Read `../skill-based-architecture/SKILL.md`, then use it to organize this project's rules." The README notes that equivalent requests such as "organize the project rules", "migrate rules to skills", or "把规则迁移到 skills 目录" route to the same migration workflow.

Before touching a private repository, use the fixture. The README points to examples/simple-repo/ as a tiny local fixture with deliberately duplicated instructions, and to examples/simple-repo/COPY-PASTE-INPUT.md when a hosted environment accepts pasted files. What you should see after a run is a preview of every create, preserve and conflict decision, then the applied result. If you never see that preview, stop and check which workflow the agent entered, because the preview is the step that keeps a migration from silently overwriting instructions.

Where SBA is the wrong tool

The README's own exclusion list is the honest starting point: temporary repositories, projects with fewer than three small rule or document files, and teams with a compact, reliable instruction system that do not want to migrate. Adding a skills/ directory to a repository with one CLAUDE.md creates a second place to look, not a single source of truth.

The second limitation is the materialization boundary itself. scaffold-downstream.sh creates the Skill owners, routes, checks and harness surfaces admitted by the evidence. It does not fill project content, merge preserved entries, or prove source-to-destination semantic equivalence. The README states the agent still owns those steps. So the script gives you structure, and the quality of the migration still depends on the agent run that follows it. If you were hoping for a deterministic converter, this is not one.

The third is harness dependence. The plugin route is documented for Claude Code. Everywhere else the README describes a clone plus an explicit path, and it says the agent needs read access and an explicit path when its harness does not discover the Skill automatically. Whether your harness discovers it is something the README leaves to the per-tool shells reference rather than promising. Test discovery on your harness before you plan a team-wide migration.

How it differs from a single AGENTS.md or a plain rules file

The obvious alternative is the thing most teams already have: one AGENTS.md or CLAUDE.md, plus a Cursor rules directory, maintained by hand. The difference in approach is routing. A rules file is loaded whole, every task, whether or not the task touches the rules it contains. SBA's model is that one task route selects one workflow, and later knowledge is pulled only when an unresolved decision needs it. That is a retrieval design, not a formatting preference, and it is the reason the project insists on a route rather than a bigger file.

The second difference is what counts as done. In the plain-rules world, a command, commit or push is often treated as completion. SBA checks completion against the current task's bound deliverables and exact requested terminal state. That distinction shows up in the README's table and in the migration workflow's verification step.

The third is lesson handling. With a rules file, a costly failure gets written into documentation and stays passive. SBA's stated model is that a proven, reusable failure is reconciled into the right owner and connected to the next task that needs it. Whether that activation works in practice depends on the agent following the route, so treat it as a design claim from the README rather than a measured outcome. If you want a lighter comparison point, the project's own docs/sba-bible.md lays out the product principles, and references/progressive-rigor.md describes the growth model for teams that want to stay small.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-08-14. The most recent release listed is v1.14.0 on 2026-05-09, following v1.13.0 on 2026-04-30, which the release title describes as "Cross-Tool Skill Scaffold, Hooks, and Self-Checking Templates". The gap between the May release and the August push means the main branch has moved since the last tagged version, so pinning to a release and tracking main are different commitments.

Upgrade cost has two parts. On the Claude Code plugin route, `/plugin marketplace update` is the documented refresh path, which is cheap. On the clone route, you are tracking a repository whose exact location is not part of the product contract, so a pull is a pull, and any local edits to the Skill tree are yours to reconcile. The README does not document rollback, so decide how you would revert a migration before you run it on a repository you care about.

Licensing is MIT, per the repository's LICENSE file and the badge in the README. MIT is permissive and places few conditions on reuse, but the generated skills/<name>/ directory contains your project's rules, and the licence on the tool says nothing about the licence on what it produces. That is a question for your own review, not one this article can settle.

Editorial conclusion

Adopt SBA when your repository already carries duplicated or contradictory instructions across AGENTS.md, CLAUDE.md, Cursor rules and README notes, and when recurring tasks need fitted verification rather than a single large SKILL.md. Do not adopt it for a temporary repository, a project with fewer than three small rule or document files, or a team that already has a compact, reliable instruction system and does not want to migrate; the README states these cases directly. Before migrating, verify three things: that your harness can read the clone path or the plugin install, that the preview step shows every create, preserve and conflict decision before anything is written, and that scaffold-downstream.sh admits the direct, folder or broad shape your repository evidence actually supports. The script does not expose a tier, profile, capability or install-mode switch, so if you expected one, that expectation is wrong.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. WoJiSama/skill-based-architecture on GitHub