Skill Smith

skill-smith

Forge and repair skills. Pick the mode from the request:

• Create — the user describes a new capability, workflow, or knowledge area to

package as a skill.

• Improve — the user names an existing skill (path or name) to review or

upgrade.

• Measure — the user wants to benchmark or validate whether a skill works

(A/B against a baseline, trigger test). See the Measure section.

If the request is ambiguous, ask one question: create, improve, or measure?

Sources of truth:

• standards.md (eager) — the authoring ruleset; every decision defers to it.

• CONTRIBUTING.md (on-demand: repo mechanics) — skill placement, naming, the

catalog-doc list, dev loop, and retiring. Follow it; never duplicate it.

Create mode

Forge a complete, standard-compliant skill end-to-end.

1. Scope it. Settle the one job this skill does, its trigger phrases, whether

it creates or packages knowledge, and its plugin group (golang, srd, craft, or a new one). Ask only what you cannot infer.

1. Read standards.md and the relevant parts of CONTRIBUTING.md.

1. Name it. Lowercase-hyphen, gerund or short verb, equals the dir name, no

reserved words or vendor prefix. Confirm the name with the user.

1. Evals first. Derive ≥ 3 scenarios from where the agent falls short without

the skill: run the task unaided, note what fails, encode each failure as a request + expected-behavior checks (≥ 1 asserting terse output). These evals are the spec the body must pass.

1. Write SKILL.md. The minimum dense imperative body that passes the evals,

per standards.md — portable frontmatter, token economy, ≤ ~500 lines, progressive disclosure, and the output-discipline line where the skill describes its output.

1. Write README.md. Concise usage + when-to-use, and an ## Evaluations

section holding the step-4 scenarios.

1. Validate & refine. Dry-run against the evals; where it struggles, fix the

skill (strengthen the description first if it fails to trigger) and repeat. Then run ./dev/lint-skills.sh and clear every error.

1. Update catalog docs per CONTRIBUTING.md's Documentation list.

1. Place & load. The skill lives at /skills//. A new group also

needs its .claude-plugin/plugin.json and a marketplace entry (existing groups need neither). Show the files and doc updates, then tell the user to run /reload-plugins to load it.

Output: the new skill files, the catalog diffs, the evals, and a one-line statement of the skill's job and triggers. Then the reload reminder.

Improve mode

Audit one named skill against the standard, report, then fix on confirmation. Reasoning only until the user approves — no edits during the audit. Default scope is the single skill named; audit a whole category only if asked.

1. Resolve the target. State the exact skill dir and files in scope. If none

was named, ask which one.

1. Read standards.md, CONTRIBUTING.md, then the target's SKILL.md,

README.md, and any bundled files.

1. Audit against standards.md — it is loaded, so walk its rule sections (see

its Contents) in order rather than re-deriving them. Two checks are easy to skip:

• Reference content — read each reference's prose, not just its structure;

flag entries that restate the rule they key to, collapse to one shared principle, run past ~2 sentences of Why/Detect, or ship a code fence the prose already makes clear; flag any step that eagerly loads a whole reference each run.

• Output discipline — the body carries the terse-output line and no step

mandates framing or restating shown content.

1. Report only. Do not edit yet.

1. Fix on confirmation. Apply the approved findings, show diffs, then run

./dev/lint-skills.sh and clear any error. If structure changed (rename, new files) follow CONTRIBUTING.md and remind the user to run /reload-plugins.

Output: group findings by severity — Blocker / Should-fix / Nit. Each finding names the file (and line if useful), the standards.md rule it violates, and a minimal fix. End with a verdict (compliant / fix-first) and per-severity counts, then offer to apply the fixes.

Measure (optional)

Prove a skill works instead of eyeballing it: A/B its README scenarios with and without the skill loaded, grade the delta, and test whether the description triggers. Follow references/evals.md. Run it as the last create step, inside improve when a skill's value is in doubt, or standalone on request. Report the result table and verdict; make no edits from a Measure run without confirmation.

Self-application

skill-smith obeys its own standard. When you change this skill, re-audit it in improve mode.

Report tersely in every mode: no preamble or narration; state each fact once; don't restate output the user can already see.

Self-learning

Read this skill's lessons and obey them: sibling LESSONS.md, else $HOME/.agent-data/ctx42-skills/lessons/craft/skill-smith.md when this directory is read-only. On a correction or self-caught mistake, append a one-line rule to whichever is writable (creating it) and report where.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ctx42
• Source: ctx42/skills
• License: MIT

Install and usage instructions live in the source repository linked above.