/skill-fy

name: skill-fy
description: >
  Load when creating a new skill, scaffolding a SKILL.md, adding a reference page to a skill, writing or tuning a skill (or their description)
  or restyling/auditing an existing skill. Carries the authoring patterns (progressive disclosure, router, voice, triggering logic) a skill is shaped with.
  Optionally use the skill to audit and transform an existing skill to the recommended shape.
license: MIT
argument-hint: "Skill-fy this skill | Audit this skill | Scaffold a skill <name>"
metadata:
  author: sherifabdlnaby
  version: "0.2.0"

skill-fy

A skill encodes ideas and patterns, sometimes prescriptions if the user explicitly asked for this.

Everything below is a default with an intent behind; You're allowed to deviate only after stating why it would be better than the default. Don't copy an example's shape verbatim into a skill it doesn't fit just to follow.

**Two modes:**

1. **Scaffold** and write the first version of a new skill. 2. **Skill-fy** an existing skill: audit it against the doctrine below, trace how an agent reads it, transform it on approval.

Both hand off a draft unless asked otherwise. Build it talking with the user, expect the user to hand edit parts, A skill gets good when its owner cuts it down to what they actually mean.

How to use THIS Skill

The skill uses progressive disclosure: each mode routes to a `references/` file holding the procedure. Read the matching one **before** planning or acting, not after. SKILL.md alone is not enough.

Load the **writing-for-agents** skill tool first when it is installed. It carries the theory this skill relies on.

Router

**Scaffold a new skill, or add a reference page to one** -> [`references/scaffold.md`](references/scaffold.md) Intake, invocation decision, layout, the skeletons, frontmatter, build order (description last), reference-page shapes (commands, inventory, on-failure), the trace before handoff.

**Skill-fy an existing skill** (audit + transform) -> [`references/skill-fy.md`](references/skill-fy.md) Inventory, the trace (one walk per task, a verdict per hop), findings with disagreements, convert on approval, the checklist. References every doctrine section below.

**Tune a description** -> [Descriptions](#descriptions) below. No reference page.

Doctrine

Encode the delta, not the whole manual

Rely on the model's world knowledge. A skill carries the practices, gotchas, and conventions the model wouldn't apply on its own, usually from user's experience and observed gotchas. Enumerating a tool's features duplicates pretraining and rots as the tool moves.

Examples, and overfitting

Model world knowledge is usually underestimated: an example of something in pretraining (how to commit, how to open a PR) teaches the model nothing, and overfit the agent to one style; the skill overfits to today's case and rots. An example is good when:

• **Output must be consistent across runs.** The skill exists to make every run produce the same

shape: a PR-body skeleton, a scaffolded CI workflow, a config template. Show the exact template (or ship it as an asset) and instruct to use it as verbatim as possible.

• **The model demonstrably errors.** A syntax it reliably miss, a flag it invents or not use correctly, a check it runs unasked. Show the wrong and the right form; one verified case is usually enough.

Otherwise state the rule and skip the example; the model knows the how.

Fast path

A skill runs many times a day; its setup and prerequisite checks runs once. Setup and prerequisite checks need to run outside of the fast happy path.

• **Assume, then act.** The tool is installed, the login is valid, the service is up. The first real command *is* the check; its failure routes to the slow path.
• **Pre-checks the fast path never carries.** Each is a habit the model has, so the skill names it:
• tool present or version. Wrong: `which gh`, `gh --version`, then `gh pr create`. Right: `gh pr create`.
• login state. Wrong: `gh auth status`, then the call. Right: the call; its auth error names the fix.
• `--help` or the docs before a command the skill already shows. Wrong: read, then run. Right: run the cached call; read on a cache miss.
• **The slow path lives behind a failure.** A reference page ends with an `On failure` block: symptom, quick fix, then a link into `setup.md` (one-time: install, auth, config) or `troubleshooting.md`

(diagnose), by scenario. Most importantly outside the main/commong/fast workflow. Example Shape in [`scaffold.md`](references/scaffold.md#reference-pages).

• **Cadence rules dependencies.** A fast-path step never waits on a slow-path one; it nags instead. (why: a skill that re-verifies its setup on every run pays the setup cost daily.)

Commands as a cache

A command in a skill is a cached lookup, not documentation. It saves the agent a `--help` on the usual call; it does not replace one.

• **Show the fast path only.** A synopsis with the flags that matter, then examples of the usual calls, in one fenced block. Do not do a walkthrough of the tool. (why: an enumerated surface duplicates

pretraining and rots as the tool moves.)

• **Declare the cache once.** SKILL.md carries one line: commands shown are the usual call, not the full surface; `--help` and current docs are authoritative. Not per block.

(why: doc voice reads as "the only way that exists"; the agent then tries variants of the cached call instead of reading `--help`.)

• **A cache miss goes to the source.** A flag the block lacks, an error it did not predict, a version that behaves differently: read `--help` or the docs, then act. One read beats three guessed

variants.

• **Synopsis over prose.** `gh pr create [--fill] [--base <branch>] [--draft]` teaches the shape in one line. The same in prose costs more and anchors to one call.
• **One wide read beats many narrow ones.** When the task consumes a lot of state anyway (a PR's reviews, checks, and files; a project'