# Skill Forge

> Write, revise and prune the skills in this set.

- Skill: `alpayc/skill-forge` (Agent Skill)
- Install (CLI): `npx get-skill add alpayc/skill-forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alpayc/skill-forge/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: AlpayC (https://skillmd.com/u/alpayc)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alpayc/skill-forge

---


# Skill forge

Maintains this skill set. Invoked by hand, because writing a skill is deliberate work.

## Before writing

Ask whether a new skill is the right answer at all. Three cheaper options usually are:

- **A line in `CLAUDE.md`** — for a fact the agent needs on every run
- **A section in an existing skill** — for a branch of something already covered
- **A wiki page** — for an answer, rather than a process

A skill earns its own file when it is a **process with steps and a completion bar** that fires in a recognisable situation. Anything else is reference, and reference belongs in the skill that reaches it.

## What makes these skills work

The set has a house style, and it is the style that carries the autonomy:

**A named failure mode up front.** Each skill opens by saying what goes wrong without it. That is what makes the steps feel necessary rather than ceremonial, and it is what an agent reaches for when deciding whether the skill applies.

**Completion criteria that are checkable and exhaustive.** Every skill ends in a `## Done when` that a run can verify against. "Every gate has exited zero and has an entry in gates.md" bounds the work; "verification is complete" does not, and the difference shows up as premature completion.

**Positive targets, not prohibitions.** A ban drags the banned behaviour into context and half-reads as an instruction. Say what to do — `agentic-guardrails`' table is the pattern: the shortcut in the left column, the real fix in the right. Where a hard guardrail cannot be phrased positively, pair it with the positive target.

**One source of truth.** The ledger, the repair budget and the shortcut list live in `agentic-guardrails` and are referenced by name from everywhere else. Restating them would put three copies out of sync within a month, and inflate their apparent rank.

**Leading words.** `green`, `ledger`, `blast radius`, `changed set`, `drift`, `evidence`, `red`. Repeated as tokens, never redefined. They cost one word and anchor a whole region of behaviour; a passage spending a sentence to gesture at one idea is a passage waiting to collapse into one.

**Environment over cache.** Commands come from `docs/agent/repo-map.md` or from the tooling, not hardcoded into the skill. A skill that hardcodes `nx test` is a skill that breaks on the first repo that is not NX.

## Writing the description

The description is the trigger, and it is loaded on every turn whether or not it fires. Two jobs: say what the material is, and list the **distinct branches** that should reach it.

- Front-load the leading word — it does its triggering work at the start
- One trigger per branch; synonyms renaming one branch are that branch written twice
- Cut identity the body already carries

Set `disable-model-invocation: true` only when the skill should fire by hand alone. It costs zero context — and costs you the memory of its existence, and stops any other skill from reaching it. Anything in a chain stays model-invoked.

## A skill earns model-invocation by being used

Writing a skill does not entitle it to a permanent line in every prompt. Thirty descriptions competing for one situation make the choice worse, not better, and the cost lands on the one thing that matters — whether the right one fires.

So the default for a new skill is **hand-invoked**, and it is promoted when you have typed `/its-name` two or three times and know the situation is real. Demote the reverse way: a skill that has not fired in a quarter goes back to hand-invoked, and nothing is lost — `/its-name` still works.

`skillOverrides` in `settings.json` does this without touching the file: `"user-invocable-only"` removes a skill from the model's reach while keeping the slash command. Use it to keep a small firing core beside a larger library, rather than deleting work that is merely not needed today.

**The core is what a chain must reach without a human.** Everything a running skill invokes by name has to stay reachable, or the chain breaks silently at that step. Everything the *human* recognises the moment for — a flaky test, a red pipeline, a design to build — belongs in the library, because noticing it is exactly the judgement a person is there for.

## Revising

Revision is mostly deletion. Working through an existing skill:

- **No-ops** — does this line change behaviour versus the default? "Be careful" does not. Delete the whole sentence rather than trimming it.
- **Duplication** — the same meaning in two skills. One keeps it; the other references it by name.
- **Sediment** — a line describing a tool, path or convention that has moved.
- **Sprawl** — the skill is simply too long, and attention thins across the excess. Push branch-specific reference into a sibling file behind a pointer, as `repo-cartograph` does with `WORKSPACE-KINDS.md`.

## Verifying

A skill is verified by **running it**, not by reading it. Pick a real task in the situation the skill claims to cover and watch for three signatures:

- It did **not fire** when it should have → the description is the problem, not the body
- It fired and the agent **skipped a step** → that step's completion criterion is too vague, or the step is buried under reference that should be disclosed
- It fired and produced the **wrong shape** → the output format is under-specified; show the template

## Done when

The skill has a named failure mode, steps with checkable criteria, a `## Done when` that is exhaustive, a description carrying its distinct triggers, no duplication of what `agentic-guardrails` owns, and one real run behind it with the three signatures checked.

