extension-architect

The master builder for Claude Code extensions. One Agent Skill that creates, tunes, refactors, audits, and researches the facts to ship elite skills, plugins, subagents, hooks, MCP servers, and output styles — for any topic, without guessing the spec.

v1.4.1 · changelog · 5 playbooks · 18 references · 15 invariants · 26 evals

It practices what it preaches: a lean SKILL.md router that pulls deep knowledge into context only when the job needs it (progressive disclosure), so it stays featherweight while knowing the whole extension surface.

---

Why this exists

Claude Code extensions fail silently. There is no error — the thing just never happens:

• a skill that never fires because its description doesn't match how people actually ask;
• a plugin that validates but never loads because its name starts with claude- (the runtime drops it);
• a SKILL.md quietly truncated after compaction because it grew past its token budget;
• an unquoted 123 in YAML that crashes the loader.

extension-architect encodes 15 of these traps as hard invariants, and every load-bearing limit in it is verified against the official Claude Code docs and cited inline — so you build on facts, not folklore.

---

What should I say?

Paste one of these into Claude Code — the skill should pick itself up from the description alone:

You want…	Try saying
Something new	"Build me a skill for reviewing Terraform PRs"
Better triggering	"My skill never fires — fix the description and eval it"
Slim it down	"This SKILL.md is 800 lines — refactor it with progressive disclosure"
A gut-check	"Audit this plugin against the live spec"
Unknown domain	"Create a skill for X — research official docs first, cite sources"

If nothing happens, the description is probably the culprit. This skill will tell you why (invariant #1).

---

Pick your adventure

flowchart TD
  A[What do you need?] --> B{Starting from scratch?}
  B -->|yes| C[playbooks/create.md]
  B -->|no| D{Skill too big / always loaded?}
  D -->|yes| E[playbooks/refactor.md]
  D -->|no| F{Won't trigger / weak quality?}
  F -->|yes| G[playbooks/optimize.md]
  F -->|no| H{Need a rubric pass?}
  H -->|yes| I[playbooks/audit.md]
  H -->|no| J{Missing domain facts?}
  J -->|yes| K[playbooks/research-augment.md]
  J -->|no| L[SKILL.md invariants + references/]
  C --> M[Chain: research → audit before ship]
  G --> M

Loading

Real work often chains playbooks: create → research-augment (unknown domain) → audit (before ship). Load one playbook at a time — never the whole library at once.

---

Install in 10 seconds

Claude Code — clone the repo, then symlink it into your skills folder:

git clone https://github.com/voidfreud/extension-architect
ln -s "$PWD/extension-architect" ~/.claude/skills/extension-architect

That's it. Next session, ask for a skill and watch it route.

Plugin / marketplace install

This repo ships a .claude-plugin/plugin.json manifest. Install via your plugin channel of choice, or point Claude Code at the repo — skills, hooks, and commands live at the plugin root, not inside .claude-plugin/ (invariant #10).

---

What's inside the box?

Layer	Role	Loaded into context…
SKILL.md	Router + 15 non-negotiable invariants	Always, while the skill is active
playbooks/	Procedures — what to do	One job at a time
references/	Facts — what is true	One topic at a time, on demand
assets/templates/	Starters for new artifacts	When creating something new
evals/	Smoke evals for this skill	Never — dev-only, runs locally

Only SKILL.md + the playbook/reference you actually open enter a session's context. scripts/, package.json, and evals/ ship for maintenance but never load — that is the progressive-disclosure selling point.

Playbooks (procedures)

File	Job
playbooks/create.md	Author a new skill / plugin / subagent / hook / slash command / MCP server / output style
playbooks/optimize.md	Tune triggering and quality (description + evals)
playbooks/refactor.md	Split and slim a bloated skill
playbooks/audit.md	Full rubric review, with per-artifact checklists
playbooks/research-augment.md	Find missing context from official sources before writing

References (knowledge)

File	Answers
references/frontmatter.md	Field meanings, exact limits, quoting traps
references/loading-and-context.md	Three-tier loading, token economics, compaction
references/descriptions.md	Triggering theory + writing + eval splits
references/structure.md	Multi-file layout, router pattern, scripts
references/power-features.md	!cmd, context: fork, allowed-tools, paths, model/effort
references/environments.md	Claude Code vs Claude.ai vs the web surface, portability
references/packaging.md	plugin.json, marketplace, install scopes, CLI
references/anti-patterns.md	Fast do-not checklist
references/troubleshooting.md	Broken / won't load / won't fire
references/hooks.md	30 hook events, handler types, JSON protocol, exit codes
references/subagents.md	Subagent frontmatter, model resolution, fork, resume
references/mcp.md	MCP servers, .mcp.json, transports, auth, channels
references/permissions.md	Allow / ask / deny rules, modes, evaluation order
references/settings.md	settings.json keys, scopes, precedence
references/memory.md	CLAUDE.md, rules, auto-memory, AGENTS.md
references/interface.md	Output styles, statusline, keybindings, themes
references/orchestration.md	Workflows, agent teams, background tasks
references/sandboxing.md	Sandboxed Bash: filesystem / network isolation

---

The 15 invariants

Violate one of these and the skill silently fails — no error, just nothing happening:

1. The description (with when_to_use appended) is the trigger. Third person, concrete, use-case first — Claude picks skills from their descriptions alone.
2. Hard, silent limits. name ≤ 64; description ≤ 1,024 (the API validation limit); combined with when_to_use ≤ 1,536 (Claude Code truncates the listing past that).
3. Keep SKILL.md under 500 lines. A docs tip, enforced here as a hard cap — every line is a recurring per-turn token cost.
4. References exactly one level deep. references/foo.md ✓, references/foo/bar.md ✗ — an empirical convention, enforced here.
5. No claude/anthropic in names. Reserved words in the Agent Skills base spec; worse, a claude- prefix passes validation, then the runtime silently drops the skill (#56246).
6. Quote bare numbers in YAML. Unquoted 123 parses as an int and crashes the loader.
7. disable-model-invocation: true removes the description from context entirely — Claude can no longer see the skill, not just "user-only."
8. context: fork with no task in the body returns nothing; pure-reference skills must not fork.
9. !command injection runs only at line start or after whitespace — otherwise it silently no-ops.
10. Plugin layout — only plugin.json lives in .claude-plugin/; every other directory sits at the plugin root.
11. Hooks block only via exit code 2 (on blockable events like PreToolUse) or a deny/block JSON decision; exit 1 is non-blocking — so a policy hook must exit 2, and a blanket finally: sys.exit(0) silently disables blocking.
12. Claude.ai ≠ Claude Code. Know your target before leaning on hooks, subagents, context: fork, or !cmd.
13. A slash command is a skill — the /name comes from the directory, not the name field.
14. Subagents don't nest — all fan-out happens at the top level, in one turn.
15. Don't guess a domain — research it. Verify against current official docs and cite inline.

The full story, with the source link for each, is in SKILL.md.

---

Maintainers: keep it honest

Facts are current as of mid-2026 and cite their sources; the spec moves. When a limit matters, confirm it at the source (playbooks/research-augment.md).

From the repo root:

./scripts/check.sh

Runs JSON validation, markdownlint, scripts/check_consistency.py (frontmatter, router fidelity, orphans, link paths, stale terms, ToC, line caps), and ruff on scripts/*.py. This is the whole gate — there is no CI; it runs locally before every commit.

First-time setup for checks

./scripts/check.sh auto-installs its tooling on first run. To do it by hand:

npm install
python3 -m venv .venv && .venv/bin/pip install -r scripts/requirements-check.txt

node_modules/, .venv/, .tools/, and .ruff_cache/ are gitignored; the dev tooling in scripts/ and package.json is committed and ships with the skill payload.

---

Contributing

Found a number that has drifted from the live spec? That is the most valuable issue you can open — the spec moves, and this skill's whole promise is staying true to it. PRs welcome; ./scripts/check.sh is the only gate.

If it saved you from a silent claude- trap, a ⭐ is appreciated.

---

License

MIT — see LICENSE. Built by @voidfreud.