/create-skill is the first skill in SMCFactory. It takes a user's intent for a new Claude Code skill and produces a conformant SKILL.md end-to-end: clarifying interview, MECE check against existing skills, draft assembly per the SMCFactory 5-section recipe, two-layer conformance audit, idempotent RESOLVER.md update.
It exists because hand-writing skills drifts. Frontmatter spec is easy to miss. Tools get renamed across Claude Code versions. Anti-patterns slip in. A meta-skill that enforces shape on every produced skill is what keeps the factory from becoming an opaque pile of files nobody has read in six months. The human keeps judgment; the tooling keeps the checklist honest.
This is the canonical install. Clone, symlink, and you have /create-skill available in every Claude Code session.
You type /create-skill <skill-name>. The skill loads its bundled references (canonical Claude Code tool catalog + frontmatter spec + a 6 KB condensation of the THFS methodology + an exemplar), runs an adaptive interview (4 questions in one batch, 1 follow-up question for category routing, optional research pass for grounding URLs and exemplars), runs a MECE check against existing skills, assembles a draft from the bundled template, runs a two-layer audit (a 10-item Bash script for deterministic checks + an in-skill latent judgment pass for quality), writes the new SKILL.md to ~/.claude/skills/<name>/, and idempotently updates ~/.claude/skills/RESOLVER.md inside category-specific managed-block markers. It exits with a printed scorecard and the install path.
It writes files. It never auto-fires. Manual invocation only (disable-model-invocation: true).
Best for ongoing updates: git pull in ~/dev/create-skill and Claude Code's live change detection picks up the new files within the current session.
git clone git@github.com:smcfactory/create-skill.git ~/dev/create-skill
ln -s ~/dev/create-skill ~/.claude/skills/create-skillSimpler, but ~/.claude/skills/create-skill becomes a git repo (with a .git/ subdir). Claude Code ignores .git/; nothing breaks. Updates are still git pull from inside the skill dir.
git clone git@github.com:smcfactory/create-skill.git ~/.claude/skills/create-skill/create-skill expects two sibling files to exist at ~/.claude/skills/. Copy them once on first install:
mkdir -p ~/.claude/skills
cp ~/dev/create-skill/bootstrap/RESOLVER.md.example ~/.claude/skills/RESOLVER.md
cp ~/dev/create-skill/bootstrap/_brain-filing-rules.md.example ~/.claude/skills/_brain-filing-rules.mdWhy this is needed: the skill's conformance audit (check #6) verifies that every skill has a row in RESOLVER.md. The very first invocation of /create-skill would fail this check on itself (the bootstrap paradox). The shipped RESOLVER.md.example already contains the create-skill row inside the meta managed markers, so the audit passes on first run.
After install, restart Claude Code (or wait for live change detection in an existing session), then:
/create-skill
# expect the slash-command to appear in autocomplete
bash ~/.claude/skills/create-skill/scripts/check-resolvable.sh ~/.claude/skills/create-skill/SKILL.md
# expect: 10/10 PASS, exit 0If the audit reports 9/10 with check #6 failing (resolver_row_present FAIL), the bootstrap step was skipped — go back and copy the two .example files into ~/.claude/skills/.
Two flag forms:
| Form | Behavior |
|---|---|
/create-skill |
Runs the normal interview flow. |
/create-skill --refresh |
Re-fetches reference-tools.md and reference-skills.md from code.claude.com, overwrites the bundled snapshots, then continues to the normal interview with fresh references. |
Two skip flags (parsed from $ARGUMENTS, can be combined):
| Flag | Behavior |
|---|---|
--no-audit |
Skip Phase 6 (conformance audit). The skill still gets written; you just don't see the scorecard. |
--no-commit |
Suppresses the optional git-commit suggestion at the end of Phase 7. (Auto-commit is OFF by default in v1 anyway.) |
WebFetchthe canonical Claude Code docs atcode.claude.com/docs/en/tools.mdand…/skills.md.Writeeach result to the bundledreference-tools.mdandreference-skills.mdwith a top-of-file note: "Snapshot takenYYYY-MM-DD. Refresh via/create-skill --refresh."- Print: "References refreshed from code.claude.com."
- Continue to Phase 1.
If --refresh is not present, skip directly to Phase 1.
Read the four bundled files in this skill's directory:
reference-tools.md— canonical Claude Code tool catalog (the only legitimate set of names forallowed-tools).reference-skills.md— Claude Code spec for SKILL.md frontmatter, lifecycle, substitutions.reference-thfs.md— runtime condensation of the SMCFactory methodology (~6 KB).examples/exemplar-skill/SKILL.md— gold-standard pattern (currently a stub; the model defers totemplates/SKILL.md.tmpluntil v0.2 ships a real exemplar).
Survey existing skills via !`ls ~/.claude/skills` (dynamic context injection — runs before the SKILL.md content reaches the model).
Read ~/.claude/skills/RESOLVER.md. If the file doesn't exist, this is the bootstrap moment — write it from scratch with the create-skill row inside the meta managed markers.
Multi-pass adaptive interview using AskUserQuestion (max 4 questions per call, ≤ 6 questions total in Pass A, plus optional Pass B research elicitation).
Pass A — structured clarification (always runs, 2 calls):
Call 1 — scope, trigger, writes, tools (4 questions):
- Q1 [scope] — Single repeatable task / Multi-step workflow / Always-on monitor / Setup or migration one-shot.
- Q2 [trigger] — Manual
/<name>only / Manual + auto-invoke / Sub-agent only / Other. - Q3 [writes] — No (read-only) / Project dir /
~/.claude// External (git push, API). - Q4 [tools] — multi-select from canonical Claude Code tools.
Call 2 — category routing (1 question):
- Q5 [category] — options dynamically discovered by greping H2 headers from
RESOLVER.md. The skill never hard-codes the category list; whatever H2s exist in yourRESOLVER.mdbecome the options.
If the user picks "Other" with a category name that doesn't exist in RESOLVER.md, Phase 2 halts and instructs the user to hand-edit RESOLVER.md to add the new H2 + empty marker pair, then re-invoke. Skills never auto-create categories — that's an architectural decision, human-owned.
Pass B — references and research (conditional, only if Pass A reveals grounding context is needed):
- Q5 (refs), Q6 (research), Q7 (exemplar), Q8 (constraints).
- Triggers when Q3 is yes-writes, OR Q4 includes WebFetch, OR the user's free-text purpose mentions a specific doc/library/site.
Pass C — execute the elicited research (no AskUserQuestion in this pass):
- For each user-supplied URL:
WebFetchwith a focused prompt. - For each user-supplied file path:
Read. Fail-soft if outside the project dir or~/.claude/. - For Agent-delegated research: spawn one
Agentcall with subagent typeExplore(isolated context, single summary message back). - For named exemplar skills:
Readto use as a structural anchor.
MECE precheck (always runs):
Glob ~/.claude/skills/*/SKILL.mdto enumerate sibling skills.Grep -l "<proposed-trigger-phrase>" ~/.claude/skills/*/SKILL.mdto detect overlap.
Halting rules before any write:
- Abstract purpose ("a productivity skill") with no concrete repeatable task → halt.
- Tool name not in
reference-tools.md(e.g.,Task,MultiEdit) → halt and surface the rename. - Referenced URL fails to fetch → halt and ask user to swap or proceed without.
- Project scope but cwd is
~→ refuse; suggest personal scope. - Category doesn't exist in
RESOLVER.md→ halt; user must hand-edit RESOLVER.md first.
Inputs: Phase 1 survey + Phase 2 answers + elicited references.
Three outcomes:
- PROCEED — write a new skill (Phase 4).
- EXTEND — open the conflicting skill in
Editmode and add to its Phases instead. Skip Phase 4 of new-skill creation; jump to a focused Edit pass. - HALT — proposal is non-MECE and ambiguous; surface the conflict to the user.
Inputs: Phase 1–3 outputs + templates/SKILL.md.tmpl + (optional) the named exemplar from Q7.
Assembled by substitution into the template, not free-form generation. The template encodes the 5-section body recipe:
# {Skill Title}
## Contract — what calling the skill guarantees
## Trigger — verbatim user phrases
## Phases — numbered procedure
## Quality gates — pass/fail criteria
## Anti-Patterns — explicit ❌ list
## Output format — what the skill prints back
Three structural enforcement checks against reference-thfs.md:
- Fat-skill check — every Phase must specify (a) which tool is called, (b) on what input, (c) expected output shape. If Phases reads like a TODO list, regenerate.
- Thin-harness check — no Phase may say "the harness will...". The harness does four things: model loop, file I/O, context, safety. Anything else belongs in the skill body.
- Latent/deterministic split check — every "verify X" or "check Y" step must declare deterministic vs latent. Mixed steps are flagged and split.
Max 2 retries on regeneration, then halt and surface the issue.
Bash(mkdir -p ~/.claude/skills/<skill-name>).Write ~/.claude/skills/<skill-name>/SKILL.mdwith the assembled draft.Edit ~/.claude/skills/RESOLVER.md— insert the row inside the category-specific managed markers<!-- BEGIN MANAGED-BY-CREATE-SKILL:<slug> -->for the category chosen in Phase 2 Q5. Idempotent: if a row with the same path exists inside those markers, update in place; otherwise append before the END marker. Other categories' markers are not touched.- (Optional)
Writeuser-specified reference snapshots if Q5 of Pass B indicated bundling.
Skipped entirely if $ARGUMENTS contains --no-audit.
Layer A — deterministic Bash audit (scripts/check-resolvable.sh):
bash scripts/check-resolvable.sh ~/.claude/skills/<name>/SKILL.md10 checks, exit codes 0 (all pass), 1 (any fail), 2 (stub sentinel). JSON output via --json. Standalone --all audits every skill in ~/.claude/skills/.
The 10 checks:
| # | Check | Det/Latent |
|---|---|---|
| 1 | skill_md_present |
D |
| 2 | frontmatter_parses |
D |
| 3 | frontmatter_spec_compliant (no version/triggers/tools/mutating) |
D |
| 4 | allowed_tools_canonical (every tool in catalog, no dead names) |
D |
| 5 | body_has_required_sections (5 H2s in order) |
D |
| 6 | resolver_row_present |
D |
| 7 | no_stub_sentinels (no CREATE_SKILL_STUB or template placeholders remain) |
D |
| 8 | mece_no_duplicate_path (RESOLVER.md unique) |
D |
| 9 | triggers_in_user_language (form-agnostic — accepts quoted phrases or descriptive English; Layer A verifies non-empty, Layer B judges quality) |
L |
| 10 | thfs_compliance (body references THFS literal or methodology doc) |
D presence / L quality |
Layer B — latent skillify-lite (in-skill judgment):
Read the produced SKILL.md and Layer A's JSON output. Score four dimensions 0–4:
- Trigger quality — real user language, or jargon?
- Phase concreteness — tool/input/output specified, or aspirational prose?
- Anti-pattern coverage — specific to this skill, or generic copy-paste?
- Output format clarity — would a fresh Claude session understand what to print back?
Sum to a 0–16 quality grade. Combine with Layer A's pass count for the final scorecard.
In v1, Layer B runs as a sub-routine inside Phase 6 (no separate skill yet). v0.2 spins it out as a standalone audit-skill once a second factory skill exists to validate the meta-pattern.
Prints:
- MECE survey result — what was checked, what overlapped, decision (PROCEED / EXTEND / HALT).
- Draft summary — one paragraph on what got assembled.
- Install path — full absolute path to the new SKILL.md.
- Audit scorecard as a table (Layer A's 10 items + Layer B's 4 dimensions).
- Suggested invocation — "Try
/<skill-name>to invoke it." - Optional commit hint —
git -C <cwd> add .claude/skills/<name>/ && git commit -m "Add /<name> skill". Never auto-commits in v1.
RESOLVER.md lives at ~/.claude/skills/RESOLVER.md. It serves three purposes:
- Human-readable factory map — Nick can see at a glance which skills exist and what they route on.
- MECE-check input —
/create-skillreads it before authoring a new skill to detect overlap. - Audit input —
check-resolvable.shgreps it to verify every skill has a row.
It is not the runtime dispatcher. Claude Code's description-field semantic match handles routing automatically. RESOLVER.md is the persistent map; the description field is the on-the-fly router.
Six H2 categories, each with its own managed marker pair:
| Category | Slug | Purpose |
|---|---|---|
| Meta (the factory itself) | meta |
Skills that author or audit other skills (/create-skill lives here) |
| Coding flows | coding |
Code authoring, review, deploy |
| Marketing flows | marketing |
Content drafting, post scheduling, engagement |
| Business-ops flows | business-ops |
Bookkeeping, contracts, vendor management |
| Setup & infrastructure | setup-infra |
Provisioning, VPS setup, install scripts (/contabo lands here) |
| Identity & access | identity |
Reserved for SOUL.md/HEARTBEAT.md equivalents post-LLM-Database |
## Coding flows
| Trigger | Skill |
| --- | --- |
| _(none yet — first coding skill bootstraps this category)_ | |
<!-- BEGIN MANAGED-BY-CREATE-SKILL:coding -->
<!-- END MANAGED-BY-CREATE-SKILL:coding -->/create-skill writes inside the markers matching the chosen category. Hand-edits between markers are overwritten on next run; hand-edits outside (the placeholder rows, the H2 header, etc.) are preserved.
The Trigger column accepts two forms, picked per skill based on what actually fires it:
- Quoted user phrases for typed/spoken triggers —
"create a skill", "new skill". Searchable, dedup-able, ideal for slash-command and description-match invocation. - Descriptive English for state/event/behavioral triggers —
User asks to write or edit code,Cron fires at quiet hours,Every inbound message. Used when no specific phrase fires the skill.
A row may mix both forms when the skill responds to either. Layer A (check-resolvable.sh check #9) only verifies the cell is non-empty; the quality judgment of "is this real user-facing language vs internal jargon?" is Layer B's job.
/create-skill does NOT auto-create categories. To add one:
- Hand-edit
~/.claude/skills/RESOLVER.md— insert a new H2 (e.g.,## DevOps & monitoring) with an empty| Trigger | Skill |table and a fresh marker pair<!-- BEGIN MANAGED-BY-CREATE-SKILL:devops --> <!-- END MANAGED-BY-CREATE-SKILL:devops -->. - Re-run
/create-skill— Q5 picks up the new category from H2 discovery.
This keeps category decisions (factory shape) human-owned and skill-authoring (factory population) automated.
Hard ceiling: 25 tool calls. Soft target: 18.
| Phase | Tool budget | Notes |
|---|---|---|
0 (--refresh) |
0 or 4 | 2 WebFetch + 2 Write, only if flag present |
| 1 (load context) | ≤4 | 3 Read + 1 Bash list |
| 2 (interview) | ≤8 | 3–5 AskUserQuestion + up to 3 WebFetch/Read/Agent in Pass C |
| 3 (MECE) | ≤2 | Glob + Grep |
| 4 (assembly) | 0 | Pure model work |
| 5 (write) | ≤4 | mkdir + Write SKILL.md + Edit RESOLVER.md + optional Write |
| 6 (audit) | ≤4 | Bash audit + Read result + optional Edit |
| 7 (report) | ≤3 | Read final + optional git Bash + summary |
Blowing the ceiling almost always means Phase 2 went too deep (too many WebFetch calls or recursive Agent dispatches). Halt and report; don't burn the budget.
create-skill/
├── README.md this file
├── LICENSE MIT
├── SKILL.md main skill, ~340 lines
├── REFRESH.md documents the --refresh flag
├── reference-tools.md snapshot of code.claude.com/docs/en/tools.md
├── reference-skills.md snapshot of code.claude.com/docs/en/skills.md
├── reference-thfs.md ~6 KB condensation of THFS methodology
├── templates/
│ ├── SKILL.md.tmpl 5-section recipe template with {{...}} placeholders
│ ├── resolver-row.tmpl single-line markdown table row
│ └── conformance-checklist.md 10-item manual sanity-check version
├── scripts/
│ └── check-resolvable.sh Bash 4+, ~360 lines, zero deps (awk/grep/sed)
├── examples/
│ └── exemplar-skill/SKILL.md stub until v0.2
└── bootstrap/
├── RESOLVER.md.example copy to ~/.claude/skills/ on first install
└── _brain-filing-rules.md.example copy to ~/.claude/skills/ on first install
SKILL.md and the three reference-*.md files are loaded into context at runtime. templates/, scripts/, and examples/ are loaded only when the skill explicitly references them. bootstrap/ is install-time only — never loaded by the running skill.
Hypothetical: you want a skill that provisions a Contabo VPS for a new SMCFactory agent.
- Run
/create-skill contabo. - Phase 1 — skill loads its references, surveys
~/.claude/skills/(sees create-skill is the only existing skill), readsRESOLVER.md. - Phase 2 Pass A Call 1:
- Q1 scope: Multi-step workflow with branching.
- Q2 trigger: Manual
/contaboonly. - Q3 writes: Yes — writes external (Contabo API + SSH).
- Q4 tools: Bash, AskUserQuestion, Read, Write.
- Phase 2 Pass A Call 2 (category):
- Q5 — options pulled from
RESOLVER.mdH2 headers: Meta / Coding flows / Marketing flows / Business-ops flows / Setup & infrastructure / Identity & access. - You pick Setup & infrastructure.
- Q5 — options pulled from
- Phase 2 Pass B — yes, since this writes to external API. You paste the Contabo API docs URL in Q5 (refs).
- Phase 2 Pass C — the skill
WebFetches the Contabo API docs, summarizes the public surface (instances API, regions, plans). - Phase 3 — MECE check: no overlap, no existing skill provisions VPSs. Decision: PROCEED.
- Phase 4 — draft assembly. Body has 5 sections: Contract (provisions a Contabo instance and returns the SSH endpoint), Trigger ("provision a contabo vps", "set up a new agent on contabo"), Phases (parse args, validate creds via Keychain, call Contabo API, wait for ready, return SSH endpoint), Quality gates (cred check, idempotency on re-run, error handling), Anti-Patterns (no plaintext creds in chat, no API key in skill body), Output format (instance ID + IP + SSH command line).
- Phase 5 —
Write ~/.claude/skills/contabo/SKILL.md,Edit ~/.claude/skills/RESOLVER.mdto insert the new row inside<!-- BEGIN MANAGED-BY-CREATE-SKILL:setup-infra -->markers. - Phase 6 — Layer A audit runs, all 10 checks pass. Layer B scores: trigger quality 4/4, phase concreteness 4/4, anti-pattern coverage 3/4 (one anti-pattern was generic), output format 4/4. Total: 15/16 latent + 10/10 deterministic.
- Phase 7 — prints scorecard, install path
~/.claude/skills/contabo/SKILL.md, suggests/contaboinvocation.
Total tool calls used: ~16. Under the 18-soft-target.
The bootstrap step was skipped. Copy the example:
cp ~/dev/create-skill/bootstrap/RESOLVER.md.example ~/.claude/skills/RESOLVER.mdYour allowed-tools list contains a renamed/removed tool. Common fixes:
Task→Agent(subagent dispatch)MultiEdit→ repeatedEditKillShell→TaskStopBashOutput→Readon the task's output fileSlashCommand→ not needed; skills are slash commandsNotebookRead→Read
Run --refresh to re-fetch the canonical catalog if you suspect drift since last snapshot.
Your SKILL.md still contains {{...}} template placeholders or the literal string CREATE_SKILL_STUB. Likely Phase 4 substitution missed a placeholder. Re-run /create-skill or hand-fix the file.
Restart Claude Code. Live change detection works for files INSIDE existing top-level skill dirs. If you renamed the skill dir (create-skill → something else) or added a top-level skill that didn't exist at session start, restart is required.
Anthropic moved the doc URLs. Update the URLs in SKILL.md Phase 0 step 1 and step 3. Then re-run /create-skill --refresh.
Open the file and search for the literal strings in STUB_SENTINELS array (top of check-resolvable.sh). Most common cause: a Quality gates or Anti-Patterns section in the SKILL.md echoes the sentinel string for documentation. Fix by referencing the sentinels indirectly (e.g., "see conformance-checklist.md item 7").
This is v1.0. Future versions on the roadmap:
- v0.2 — spin out Layer B (skillify-lite) as a standalone
/audit-skillonce a second factory skill exists. Improves modularity; the audit can then run against hand-written skills, not just/create-skilloutputs. - v0.3 — draft validation pre-Phase 5 (frontmatter completeness, tool-name correctness checked before the file lands on disk). Catches errors earlier than the post-write audit.
- v0.4 — optional git auto-commit at end of Phase 7. Currently OFF by default; v0.4 makes it opt-in via
--commitflag. - v1.0+ (parked) — auto-mode trigger detection. Watches user prompts for repeated patterns and suggests
/create-skillrather than auto-firing it. Preserves the human-keeps-judgment doctrine.
This is a private SMCFactory repo. Pull requests from outside the org are not accepted.
For SMCFactory contributors: open a PR against main. Every change to SKILL.md should be accompanied by a re-run of bash scripts/check-resolvable.sh ~/.claude/skills/create-skill/SKILL.md and a paste of the 10/10 PASS scorecard in the PR description. CI will run the same check automatically.
MIT — Copyright (c) 2026 SMCFactory.