skill-forge

Most skills fail the same way: somebody wrote the file before they had run the task. The file then encodes a guess, and the guess is obeyed.

The order is the whole method

1. Name the pain, then the problem, then the prompt. If you cannot say what specifically goes wrong today, you are building for a problem nobody has. Stop here more often than feels comfortable.
2. Run it by hand as a plain prompt. Not once. Until the output is right and you know why it is right.
3. Write the playbook. Five parts, all of them: the rules, the steps, the standards for good output, worked examples, and the never-dos. This is prose, not a file format.
4. Only now write SKILL.md, from the playbook.
5. Test it against the cases that broke in step 2.

Skipping from 1 to 4 is the failure this skill exists to prevent.

Rules for the file itself

One task per skill. The test: would you ever run this task on its own? If no, it is a step, not a skill. Skills that do five things or chain several events do not get obeyed. Chain narrow skills instead.

Open with one sentence saying what this is, above all the detail. Detail placed above purpose outvotes the purpose.

Length is a constraint, not a budget. A long skill stops being followed. Instructions belong in SKILL.md. Facts about a project, a person or a corpus belong in a referenced file the skill points at.

Write non-negotiables as prohibitions, not as tone. "Never invent a client name" is enforceable. "Be accurate" is not. Anything that goes out under a real name needs its prohibitions written as hard lines.

Include the negative examples. What a wrong answer looks like teaches more than another right one.

A human-in-the-loop step is a feature. A skill that interviews you before producing is often better than one that one-shots. Do not optimize that away.

When a chained step keeps returning the same answer

Give it its own turn rather than more instructions. A step folded into a larger skill collapses toward its own first answer. Splitting it out fixes what more prompting does not.

The self-score gate

For anything with a quality bar, make the skill score its own output against its own rules and refuse to deliver under a threshold. It converts standards you wrote down into standards that get checked.

Never install a found skill unopened

A skill from a marketplace or a repo is inspiration, not a dependency. Read what it actually does first: it runs with your permissions, your files and your credentials. Prefer add-skill.sh, which clones rather than vendors and prints the declared license before installing, because a badge saying Apache 2.0 can sit on top of a proprietary or AGPL skill that relicenses a project by contagion.

Naming and versioning

Kebab-case directory matching the skill name. When a skill is versioned, put the version at the front of the title, because names truncate from the right and the one question worth answering at a glance is whether this is current.

Registry drift is a test, not a paragraph

If skills are listed anywhere, generate the list from the frontmatter and add a check that fails when it drifts. A hand-maintained index rots, and the rot is silent.