skill-fy · diff
v0.1.0 to v0.2.0
97 added, 26 removed. Audit A to A.
---
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's description, or restyling/auditing an existing skill.
- Carries the authoring patterns (progressive disclosure, router, voice, triggering) a skill is shaped with.
+ 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: "[scaffold <name> | restyle <skill> | description <skill>]"
+ argument-hint: "Skill-fy this skill | Audit this skill | Scaffold a skill <name>"
metadata:
author: sherifabdlnaby
- version: "0.1.0"
+ version: "0.2.0"
---
# skill-fy
- A skill encodes ideas and patterns, not specific prescriptions. Everything below is a default with an intent behind it;
- deviate when you can state what following it would cost the skill at hand. Don't copy an example's shape verbatim into a skill it doesn't fit just to follow.
+ A skill encodes ideas and patterns, sometimes prescriptions if the user explicitly asked for this.
- ## Scaffolding
+ 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.
- This skill scaffolds and writes the first version of a skill. It does not ship the final one.
- Build it talking with the user: the calls that shape the skill (what it encodes, who fires it, how it splits) are theirs, ask instead of assuming.
- And expect and ask the user to come back and trim. A skill gets good when its owner cuts it down to what they actually mean, so hand off the draft with a note on what you'd cut first.
+ **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 manual
+ ### 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
- A lot of skill guidance, especially early ones focused too much on mentioning examples.
-
Model world knowledge is usually underestimated:
- an example of something in pretraining (how to commit, how to open a PR) teaches nothing,
- and anchors the agent to one instance; the skill overfits to today's case and rots. It's a delicate balance. An example is good when:
+ 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 if it's something expected to be consistent.
+ (or ship it as an asset) and instruct to use it as verbatim as possible.
- - **The model demonstrably errs.** A syntax it reliably flips, a flag it invents. Show the wrong and the right form; one verified case is enough.
+ - **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's tool versions), cache one piped command that gathers all of it
+ in a single call. Multi-line is fine; it must paste and run as one unit.
+ - **Save the wide read, query it locally.** Write the output to a temp file once and `jq` it as questions come up. (why: each re-run is a round trip and a chance to drift; a file answers every
+ follow-up for free.)
+ - **A wide read is not a pre-check.** It runs because the task needs the data, not to confirm the tool exists. The fast-path rule still holds.
+
+ ### Environment
+
+ A skill runs on more than one host/environment. Think along the following axes, declare the result, and do not probe for it.
+
+ - **Axes.**
+ - Network and sandbox (no network, no installs, read-only tree).
+ - System tools and services (a CLI, Docker, VPN, a running local service).
+ - **Declare only when there is something to declare.** A skill that needs anything beyond the model and the filesystem ends SKILL.md with a `## Compatibility` section: a `Needs:` line, and a `Hosts:`
+ line with a verdict and reason per host. A skill with no needs has no section. Shape in the [skeleton](assets/SKILL-skeleton.md).
+ - **Assume present** bail early on failure on a listed unsupported host. The goal is for the skill to fail gracefully and not get the agents into loops until they figure out they're in a sandbox.
+
+ ### Interactive vs autonomous
+
+ A skill need to differentiate and be aware of when the skill is triggered via autonomous unattended system (Cron, Trigger, etc), or by a Human (Interactive).
+ A skill workflow need to declare both so we can easily add conditions (if interactive do that), (unless autonomous, confirm with user ) and so on. Build this in the doctrine of the skill you build.
+
### Progressive disclosure
A small skill is one SKILL.md. When distinct tasks need distinct rules, SKILL.md becomes a router:
cross-cutting, easily-missed doctrine stays in SKILL.md; each clear task's rules move to a `references/` page.
Inline what every path needs; push down what only one path reads.
- Don't scaffold `references/` speculatively. Don't over do it ... too many references means we rely more on the Agent deciding the perfect references.
+ Don't scaffold `references/` speculatively. Too many references means relying on the agent to pick the perfect one every time.
A router entry names the task the agent is about to do (not the topic), then gives a keyword-dense line of the page's contents so the agent picks without opening, e.g.:
```markdown
**Committing** -> [`references/commits.md`](references/commits.md)
Pre-staging walk, message style, hook-failure handling, scoping, empty commits.
```
The router isn't the only path between pages: references link sideways to each other wherever their rules touch, so an agent landing on one page still finds the rest. Mechanics in
[`scaffold.md`](references/scaffold.md#reference-pages).
+ The split is right when the trace says so: each task loads its own few pages, no page is loaded by every task, none is loaded by no task. The trace lives in
+ [`skill-fy.md`](references/skill-fy.md#2-trace).
+
### Teach the reader how to read
A routed skill tells its agent, in SKILL.md, how to consume it:
- **Read the matching reference before planning or acting, not after.** Rules shape the plan; reading them late means redoing it. SKILL.md alone is not enough.
- - **At least one reference per task**; several tasks, several references, this force model to think what to pick.
+ - **At least one reference per task**; several tasks, several references, this forces the model to think what to pick.
- **Local references eager, online links lazy.** Default to trusting model knowledge; go online only to learn more, or double check.
- **Link the authoritative docs as the escape hatch**: when the tool moves fast or reality disagrees with the skill, check the current docs and changelog instead.
### Voice
Skill prose is direct doctrine written for a stranger agent mid-task, with no access to the conversation that authored it.
- **No bullshit**, no performative wording. Just concise/dense and direct instructions.
- **Concise against your instincts.** A generated draft runs verbose and over-enumerated by default;
a skill is the opposite artifact: a distillate of few rules, each earning its context cost.
When coverage and concision fight, concision wins; world knowledge fills the gaps.
- **Strip pass** after every draft: remove audience narration ("engineers often..."), authoring-session residue ("as discussed"), and rhetorical flourish. State the model and the instruction; keep a
why only as mechanism, not story.
- **Bold lead-ins.** `**Rule.** mechanics.` One rule per bullet; pages stay scannable.
- - **Why as protection.** Attach `(why: ...)` where the reason stops a wrong move — "fixing" a deliberate choice, removing a needed workaround. Obvious whys are noise.
+ - **Why as protection.** Attach `(why: ...)` where the reason stops a wrong move: "fixing" a deliberate choice, removing a needed workaround. Obvious whys are noise.
- **Leading words.** Prefer one strong pretrained concept over a restated triad ("a *tight* loop" over "fast, deterministic, low-overhead").
- **Rot-resistant.** Name the set, not its members (mark examples `e.g.`). Skip counts, versions, and file lists that rot; version-stamp only claims actually verified ("verified on X 1.2").
### Descriptions
Written last, once the tasks are real. A model-invoked skill pays for its description in context every turn.
A manual-only skill (`disable-model-invocation: true`) costs nothing, the user is its index; keep its description one neutral line without trigger phrasing.
(why: some harnesses ignore the invocation-off flag, and a trigger-rich description auto-fires the skill anyway.)
For model-invoked:
- **Short, made of words attention snags on.** Concrete action verbs first: "Load when about to commit, branch, push..."
- - **Focus on Triggering**: Only target on what makes an Agent/User know to use the skill, don't enumerate what the skill does inside in the description, only what get someone who merely knows some
- keywords get to trigger the skill.
+ - **Focus on triggering.** Only what makes an agent or user know to use the skill; don't enumerate what the skill does inside. Someone who merely knows some keywords should land on it.
- **Say when not to load, only for common misfires.** A tool touched constantly earns its anti-trigger
("don't load for routine use that isn't changing config"); a rare misfire doesn't earn the words.
- (e.g don't load mise skill just to run mise install, only when modifying mise.toml)
- ## Router
+ ## Always applies
- **Scaffold or restructure a skill** -> [`references/scaffold.md`](references/scaffold.md)
- Intake, invocation decision, layout, assets and the starter skeleton, frontmatter, build order (description last), reference-page patterns, variants, optional shapes skills sometimes take.
+ Process floor for both modes; hold to it even when fixated on one task.
+
+ 1. **The owner decides.** Put every shaping call to the user; the audit argues, it does not overrule.
+ 2. **Trace before handoff.** Every draft and every audit walks the graph once ([`skill-fy.md`](references/skill-fy.md#2-trace)); an orphan page or a performative split never ships.
+ 3. **Strip pass, then description.** Voice strip over everything, then the description, last.
+ 4. **Copy shapes from the skeletons**, never retype them from prose. A copied file doesn't drift.
+ 5. **Hand off as a draft** with a note on what you'd cut first.