Skillsmith

skillsmith

You are turning a description of desired expertise into a real, well-formed Claude Skill. Do this as a genuine multi-step workflow, not by writing a SKILL.md straight from the user's first sentence — the interview and the validation pass are what make the result good.

0. Read the standards first

Before drafting anything, read reference/best-practices.md in this same skill folder. It's the exact checklist to draft against — frontmatter rules, when to split content into reference files, structure over narrative, when a script is actually warranted, and the common failure modes to avoid. This is the same document the standalone skillsmith CLI feeds into its generation prompt, so skills produced either way meet the same bar.

1. Interview

Ask these one or two at a time in conversation — don't dump them as a giant form. Move on once you have enough to draft something concrete; you can always come back for more detail before finalizing.

1. Domain, in one sentence. What should this skill make Claude good at?
2. Trigger condition. Should it fire proactively whenever a matching task/file/request shows up, or only when the user explicitly invokes it by name? This shapes the frontmatter description directly.
3. The actual expertise. The real process, checklist, or standards to encode — ask for as much concrete detail as the user has. If they have an existing checklist, style guide, or set of examples, offer to read it (a file path, a pasted doc, a link) rather than having them retype it — distill it into reference files rather than pasting it wholesale.
4. Known pitfalls or edge cases. What commonly goes wrong, or what should this skill watch out for?
5. Deterministic logic. Is there any calculation or validation that should be a script rather than judgment calls? Only include one if the answer is genuinely yes — see the standards doc's guidance on this.
6. Anything else — tone, format, examples they specifically want included.

Use a short name slug (lowercase-hyphenated) for the skill folder — derive one from the domain if the user doesn't offer one.

2. Draft

Write the files for a new skill folder (suggest ./skills/<name>/ unless the user wants it elsewhere):

• SKILL.md — correct frontmatter, then a concise, structured body (steps, checklists, decision rules). Link to reference files for anything long rather than inlining it.
• reference/*.md as needed — distilled detail, checklists, worked examples.
• scripts/* only if step 1.5 genuinely warranted it, with real runnable logic and a note in SKILL.md on when to reach for it.

Every path must be relative to the skill's own folder. Every reference file you link from SKILL.md must actually exist among the files you write.

3. Validate

Check your own draft against reference/best-practices.md before calling it done:

• Frontmatter has a valid lowercase-hyphenated name and a description that states both what the skill does and when to use it.
• SKILL.md isn't sprawling — long detail lives in reference files instead.
• No dangling links (a reference mentioned but never written) and no orphan reference files (written but never linked from anywhere).
• No duplicated content copy-pasted across two files.

If this repository's skillsmith package happens to be installed nearby (check for a local node_modules/.bin/skillsmith or a global install), you can also literally run skillsmith validate <path> for a mechanical second opinion — but don't treat its absence as a blocker; the checklist above is the same logic that command runs, and doing it by hand is the whole point of this skill working standalone.

4. Package and deliver

Zip the finished folder into <name>.skill (a plain zip with that extension — see this session's own skill-saving convention: sending a .skill file to the user this way may offer them a save option depending on their account settings). Show them the draft first if there's any doubt about quality; iterate on feedback before packaging.

5. Iterate

Treat the first draft as a draft. Ask if the checklist, tone, or scope matches what they had in mind, and refine before finalizing — a skill that's almost right but never gets a second pass is worse than one more question.