Skill-Based Architecture plugin
A meta-skill that folds rules scattered across AGENTS.md, CLAUDE.md and Cursor files into one project skill with task routes.
- 622 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The scaffold-downstream.sh script with --apply creates folders and files in the repository, although it previews by default.
- Following the skill, the agent rewrites and merges project instructions, so the result should be reviewed in git diff.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/skill-based-architectureDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The scaffold-downstream.sh script with --apply creates folders and files in the repository, although it previews by default.
- Following the skill, the agent rewrites and merges project instructions, so the result should be reviewed in git diff.
This is third-party code. Review the repository files before installing.
What it does
The skill reads a repository and folds duplicated instructions into one project skill under skills/<name>/. It finds instructions in AGENTS.md, CLAUDE.md, Cursor rules and the README, separates rules from procedures and from facts about the code, picks one workflow per task and loads knowledge only when an open decision cannot be made without it. The skill chooses the result's shape from the repository itself: a single SKILL.md, a folder with rules and procedures, or a full structure with routing.yaml. The scaffold-downstream.sh script by default only previews what would be created, preserved or flagged as a conflict, and writes files only with --apply. Existing entry files stay untouched until the agent merges them by hand; a failed run rolls back whatever it created. After migration, structural checks run: links, file reachability, SKILL.md line budgets and coverage of each source clause. Thin shells for Claude Code, Cursor, Codex, Gemini CLI and Windsurf point to one source.
Who it is for. Teams and solo developers whose agent instructions have drifted across several files and contradict each other, or whose single SKILL.md has outgrown a readable size.
Good fit when
- The same rules are copied across AGENTS.md, CLAUDE.md and Cursor rules, and have started to diverge.
- A SKILL.md runs past 150 lines and mixes rules, procedures and reference.
- Recurring project tasks need procedures and completion checks, but the agent stops at an intermediate step.
- Costly mistakes keep recurring because the lesson is written down but never triggered at the right moment.
- Several agents should read the same project knowledge without three parallel rule sets.
Not a fit when
- The repository is temporary or has fewer than three small rule files: the author calls SBA unnecessary there.
- The team already runs a compact, reliable instruction system and does not plan to migrate it.
- You need an execution runtime or a task database: SBA stays a skill and is neither.
Example request
Use skill-based-architecture to organize this project's rules.Limitations
Structural checks do not prove that the meaning of every old instruction survived. Coverage and verbatim transfers are checked by scripts, while rephrased wording relies on a recorded manual review.
Agent behavior is tested separately, and those runs are opt-in.
The repository documentation carries many procedures and terms: Task Anchor, routing.yaml, Progressive Rigor. On a small project, learning them takes longer than they save.
How to disable. Run /plugin uninstall for skill-based-architecture or delete the clone. The generated skills/<name>/ folder and preserved entry files can stay; they work without the plugin.
FAQ
How do I install Skill-Based Architecture in Claude Code?
Run /plugin marketplace add WoJiSama/skill-based-architecture, then /plugin install skill-based-architecture@skill-based-architecture. Update the marketplace with /plugin marketplace update.
How do I use it in Cursor, Codex or Gemini CLI?
Clone the repository next to your project and ask the agent to read SKILL.md by explicit path. Entry-file details for each agent are in references/per-tool-shells.md.
What will the script do to my files?
Without --apply it writes nothing and lists CREATE, PRESERVE and CONFLICT decisions. With --apply it creates only the admitted folders and leaves existing AGENTS.md and CLAUDE.md alone.
Are sub-agents required?
No. They speed things up, but without them the agent does the same work sequentially and the checks are not weakened.
Does it suit a small project?
In a trimmed form: for a small repository it picks a single SKILL.md. The author advises against it for a temporary repository.
Discussion
No questions or reviews yet.
Related
PluginsA skill that turns a pile of skills into a routing tree so the agent loads only the leaves it needs
Self-learning
self-learning-skills
A meta-skill that saves a hard-won working procedure as a new skill or rule, so the next session starts already knowing it
A desktop app and CLI to install, sync and organize agent skills across Claude Code, Codex, Cursor and other tools
A skill that designs, tests, evaluates and packages other agent skills, starting from architecture
A skill with 25 commands to audit and improve the prompts, tools and agent designs of a project in Cursor, Claude Code and Codex
A CLI that compiles a SKILL.md file into a standalone Python agent with tools, knowledge-base retrieval and its own runner.
README in short
The README opens with a "without SBA and with SBA" table, lists when the method fits and when it is excessive, and gives a two-step quick start. It continues with a single-task flow diagram, a table of guarantees, harness compatibility and a FAQ.