Skill-Based Architecture: a meta-skill that turns a repository's scattered agent rules into one project Skill
A meta-skill that produces skills. Point it at any codebase and it distills the project's rules, workflows, and hard-won lessons into a dedicated skills/<name>/ directory — a project skill that becomes the single source of truth every AI agent (Cursor, Claude Code, Codex, Windsurf, Gemini) consults before every task.
At a glance
- What is it?
- SBA is a Shell meta-skill that inventories a target repository and derives a skills/<name>/ directory holding the project's rules, workflows and verification checks. It is aimed at repositories where agent instructions have been duplicated across AGENTS.md, CLAUDE.md and tool-specific rule files, and it is explicitly not an agent runtime, task database or execution layer.
- Who is it for?
- Adopt SBA if your repository already has conflicting or duplicated instruction files across two or more agent harnesses, or if a single SKILL.md has grown past the point where a task can be routed through it without reading the whole thing. Skip it for temporary repositories, projects with fewer than three small rule or document files, and teams that already run a compact instruction system they do not want to migrate.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 33 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem SBA targets: the same rule living in four files
The README states the failure mode plainly: the same rule gets copied across AGENTS.md, CLAUDE.md, Cursor rules and README notes. Once that happens, no single file is authoritative. An agent reading CLAUDE.md may follow a rule that Cursor's rule file contradicts, and nothing in the repository records which one is current. SBA's answer is ownership. Complete meaning gets one owner, and the tool entry files keep only the local hook needed to reach it. That is a structural claim, not a formatting one: the project Skill becomes the place where a rule is defined, and AGENTS.md or CLAUDE.md becomes a pointer.
The second problem is loading cost. Most setups hand the agent one large instruction file per task, which means every task pays for context it does not need. SBA routes a task to one workflow and pulls later knowledge only when an unresolved decision requires it. The README frames this as "one task route selects one workflow." The intended audience is a repository with recurring tasks, fitted verification needs, and more than one harness in play. The README is direct about the inverse case: small projects should stay small, and SBA is usually unnecessary for a temporary repository or a project with fewer than three small rule or document files.
What the agent actually does after you ask it to organize the rules
The entry point is a natural-language request, not a CLI invocation. With the Claude Code plugin installed, the request is a sentence like "Use skill-based-architecture to organize this project's rules." With a local clone, the request names the file: read ../skill-based-architecture/SKILL.md, then use it. The README says equivalent phrasings ("organize the project rules", "migrate rules to skills") route to the same migration workflow, so the routing is on intent rather than exact wording.
From there the agent owns a five-step sequence described in the README: inventory existing instruction entries and inspect the smallest repository evidence needed to understand the project; calibrate user-confirmed product or business meaning while keeping it distinct from current implementation facts; derive the evidence-selected physical shape and admitted owners; preview every create, preserve and conflict decision before writing, then apply and semantically merge preserved instructions; and verify both the generated structure and the source-to-destination evidence for the migrated meaning.
The split of authority is the interesting part. The README says the user should only be asked about a real product or business choice, an authority boundary, or a high-cost tradeoff that repository evidence cannot decide. Everything else is the agent's engineering work. That means the tool is deliberately not a wizard that asks you twenty questions about your project; it reads the repository and only escalates what reading cannot settle.
direct, folder, broad: how the target repository picks its own shape
SBA does not offer tiers, profiles, capability packs or installation modes, and the README calls this out twice, including in a note on the current materialization boundary. Instead, scripts/scaffold-downstream.sh inventories the target and derives one of three shapes: direct, folder or broad. The shape is selected from repository evidence rather than from a user setting.
That is a defensible design choice and also the part of the project with the thinnest public documentation in the supplied material. The README names the three shapes and states they are evidence-selected, but it does not give the thresholds that separate them. A reader cannot tell from the README alone whether three instruction files produce direct and twelve produce broad, or whether the deciding factor is file count, file size, or how much the files disagree. The reference file references/progressive-rigor.md is cited as the growth model, so the detail presumably lives there, but a prospective adopter evaluating the tool from the README has to take the classification on trust.
The README is also explicit that the scaffold script has a boundary. It creates only the Skill owners, routes, checks and harness surfaces admitted by the evidence. It does not fill in project content, merge preserved entries, or produce the source-to-destination semantic evidence. Those remain the agent's job before migration counts as complete. So scaffold-downstream.sh is a structural generator, not a finished migration.
Getting it running: two plugin commands or one clone
For Claude Code, the README gives two commands:
/plugin marketplace add WoJiSama/skill-based-architecture /plugin install skill-based-architecture@skill-based-architecture
It also notes /plugin marketplace update as the way to pull the latest marketplace version. For Cursor, Codex, Gemini, Windsurf, OpenCode or another file-aware harness, the README gives a clone instead:
git clone https://github.com/WoJiSama/skill-based-architecture.git ../skill-based-architecture
The README states that the exact clone 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. Tool-specific entry options are in references/per-tool-shells.md.
There is no configuration file to edit, no environment variable to set and no config key documented in the supplied material. The only real inputs are the path to the Skill and the target repository. The README mentions no required runtime beyond a file-aware harness and Shell for the scaffold script, and the repository's primary language is listed as Shell. If you need to know what the scaffold script writes before it writes it, the README says the agent previews every create, preserve and conflict decision first; that preview is the closest thing to a dry-run described in the material.
The boundary the README draws around itself
The README opens with a disclaimer that reads like a response to over-reading: SBA is a Skill, not an agent operating system, task database, or execution runtime. That sentence does real work. If you arrive expecting SBA to schedule tasks, hold state between runs, or execute your build, you have the wrong tool. It organizes instructions and verification criteria; it does not run anything on your behalf beyond the scaffold script.
The second limitation is scope of applicability, and the README states it rather than hiding it. SBA is usually unnecessary 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. That last clause matters: the tool assumes migration is desirable. A team with one well-maintained AGENTS.md and no second harness would spend effort moving rules from a working system into a generated one, and the README does not claim a benefit for that case.
The third limitation is the one the README admits about its own current state. The materialization boundary note says the scaffold script does not expose a tier, profile, capability or install-mode switch, and that project-content filling, preserved-entry merging and semantic evidence all remain with the agent. In practice that means output quality depends on the agent doing the non-mechanical half correctly. Two runs against the same repository could produce different filled content, and the README offers no verification harness for that beyond the agent's own check.
How it differs from a single hand-written AGENTS.md
The obvious alternative is the thing most teams already do: write one AGENTS.md or CLAUDE.md and keep it current by hand. The difference in approach is not file format, it is who resolves conflicts. A hand-written file is a flat list of rules with no routing and no ownership model; when two rules disagree, the reader decides. SBA's model assigns each piece of meaning one owner and routes a task to one workflow, so a conflict is supposed to surface at migration time as a preserve-or-conflict decision rather than at task time as an ambiguity.
That trade has a cost the README does not dwell on. A flat AGENTS.md is trivially reviewable in a pull request. A generated skills/ tree with owners, routes and checks is a structure, and reviewing a structure for correctness is harder than reading a list. SBA's answer to this is the preview step and the source-to-destination evidence check, which are the mechanisms that make the migration auditable. If those two steps are skipped or done loosely, the generated tree is harder to trust than the file it replaced, not easier.
The other difference is multi-harness reach. A single AGENTS.md works for whichever tool reads AGENTS.md. SBA's stated goal is that several harnesses share one project knowledge base without maintaining several rule systems. That is a real problem for teams running Cursor alongside Claude Code, and it is the case where the ownership model earns its complexity.
Licence, maintenance and what a version upgrade costs you
The repository is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the standard permissive arrangement and it places no copyleft obligation on the skills/ directory SBA generates in your own repository. SBA is a tool that writes files into your project; those files are yours, and nothing in the MIT terms suggests otherwise. This is a description of the licence text, not legal advice, and if the generated output incorporates third-party instruction text you should check that text's own terms.
The release cadence visible in the supplied material is roughly one minor version every one to two weeks across the two most recent entries: v1.14.0 on 2026-05-09 and v1.13.0 on 2026-04-30, the latter titled "Cross-Tool Skill Scaffold, Hooks, and Self-Checking Templates." That title tells you what changed in one release, and it also tells you the generated scaffold has changed shape recently. If you generated a skills/ tree under v1.13.0, the v1.14.0 output may differ, and the README does not describe an upgrade path for already-generated trees. The scaffold script derives shape from repository evidence, so re-running it against a repository that already contains a generated tree is the case the material does not cover. Treat the generated directory as something you own and review rather than something you regenerate on every release.
Maintenance cost on the SBA side is low: clone or plugin install, no config, no daemon. Maintenance cost on your side is the real number. Every rule you migrate has to be checked once, and every future rule change now has an owner to update instead of a file to append to.
Who should adopt it and what to check before you do
Adopt SBA when the pressure it describes is already present in your repository: duplicated or contradictory instructions across agent entry files, a SKILL.md that has become hard to route through, recurring tasks that need fitted verification, or several harnesses that need the same project knowledge. The README's own fit criteria are that specific, and it is worth holding the tool to them rather than adopting it because the ownership model sounds tidy.
Do not adopt it for a temporary repository, a project with fewer than three small rule or document files, or a team with a compact instruction system it does not want to migrate. The README says all three cases are usually not worth the effort, and nothing in the material contradicts that.
The first thing to verify is the preview. Run scripts/scaffold-downstream.sh against a copy of the repository and read every create, preserve and conflict decision it lists before anything is written to the real tree. The conflict entries are the useful output: they are the places where your existing instruction files disagree, and they tell you whether your rule set is coherent enough for a single owner to make sense. The second thing to verify is the shape it picks. If the script classifies your repository as direct when you expected folder or broad, read references/progressive-rigor.md before accepting it, because the README does not publish the thresholds. The third is the harness list: confirm your tool appears in references/per-tool-shells.md, since the README's clone instructions assume a file-aware harness that can be pointed at an explicit path.
Editorial conclusion
Adopt SBA if your repository already has conflicting or duplicated instruction files across two or more agent harnesses, or if a single SKILL.md has grown past the point where a task can be routed through it without reading the whole thing. Skip it for temporary repositories, projects with fewer than three small rule or document files, and teams that already run a compact instruction system they do not want to migrate. Before committing, run scripts/scaffold-downstream.sh against a copy of the repository and read the preview of every create, preserve and conflict decision it produces; that preview, not the README table, is the real measure of whether your instruction set is coherent enough to merge.
Community notes