skill-architect

The master builder for Claude skills — one Agent Skill that creates, tunes, splits, audits, and researches domain context so you can ship elite skills for any topic without guessing the spec.

It practices what it preaches: a lean SKILL.md router that loads deep knowledge only when the job needs it (progressive disclosure), so it stays light on context while still knowing everything.

v1.1.0 · mid-2026 spec · MIT · changelog

---

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 — symlink or copy this repo into your skills folder:

ln -s "$PWD" ~/.claude/skills/skill-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	Load when…
SKILL.md	Router + 15 non-negotiable invariants	Always (when the skill is active)
playbooks/	Procedures — what to do	One job at a time
references/	Facts — what is true	One topic at a time
assets/templates/	Starters for new artifacts	Creating something new
evals/	Smoke evals for this skill	Optimizing / CI

Playbooks (procedures)

File	Job
playbooks/create.md	Author a new skill / plugin / subagent / hook / slash command
playbooks/optimize.md	Tune triggering and quality (description + evals)
playbooks/refactor.md	Split and slim a bloated skill
playbooks/audit.md	Full rubric review
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	Hooks, !cmd, fork, allowed-tools, subagents
references/environments.md	Claude Code vs Claude.ai portability
references/packaging.md	plugin.json, marketplace, install scopes
references/anti-patterns.md	Fast do-not checklist
references/troubleshooting.md	Broken / won't load / won't fire

---

The 15 invariants (cheat sheet)

Violate these and the skill silently fails — no error, just nothing happening.

Click to expand — or read the full story in SKILL.md

1. description is the only trigger — third person, concrete, use-case first.
2. Hard limits — name ≤ 64; description ≤ 1024; combined with when_to_use ≤ 1536.
3. SKILL.md ≤ 500 lines total — every line costs tokens every active turn.
4. References one level deep — references/foo.md ✓, nested ✗.
5. Never prefix claude- or anthropic- — validator passes, runtime drops.
6. Quote bare numbers in YAML — 123 becomes an int and crashes.
7. disable-model-invocation: true removes description from context entirely.
8. context: fork without a task in the body returns nothing.
9. !command injection only works at line start or after whitespace.
10. Plugin layout — only plugin.json in .claude-plugin/.
11. Hooks must exit 0 — crashed hook blocks the user's tool call.
12. Claude.ai ≠ Claude Code — know your target before leaning on power features.
13. Slash commands — name comes from the directory, not name field.
14. Subagents don't nest — fan-out at top level, one turn.
15. Don't guess domains — research, verify, cite.

---

Maintainers: keep it honest

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

From repo root:

./scripts/check.sh

Runs JSON validation, markdownlint, scripts/check_consistency.py (frontmatter, router fidelity, orphans, paths, stale terms), and ruff on scripts/*.py.

First-time setup for checks

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

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

---

License

MIT — see LICENSE.

Built by @voidfreud. If this skill saved you from a silent claude- prefix trap, you're welcome.