writing-great-skills

Name: writing-great-skills
Author: rengwu

59stars1forks

How to install writing-great-skills?

rengwu/wayfinder-maps/writing-great-skills

$npx -y skills add rengwu/wayfinder-maps --skill writing-great-skills

Installs into the current project.

Summary

Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.

Files · 1

View on GitHub

SKILL.md

1	A skill exists to wrangle determinism out of a stochastic system. Predictability — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.
2
3	Bold terms are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning.
4
5	## Invocation
6
7	Two choices, trading different costs:
8
9	- A model-invoked skill keeps a description, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to context load — the description sits in the window every turn. Mechanics: mark it model-invoked in your harness's frontmatter (in most harnesses, simply keep the `description` and omit any `disable-model-invocation` flag), and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
10	- A user-invoked skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends cognitive load: _you_ are the index that must remember it exists. Mechanics: mark it user-invoked in your harness's frontmatter (`disable-model-invocation: true` where supported); the `description` becomes human-facing — a one-line summary, trigger lists stripped.
11
12	Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
13
14	When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a router skill: one user-invoked skill that names the others and when to reach for each.
15
16	## Writing the description
17
18	A model-invoked description does two jobs — state what the skill is, and list the branches that should trigger it. Every word increases context load, so a description earns even harder pruning than the body:
19
20	- Front-load the skill's leading word — the description is where it does its invocation work.
21	- One trigger per branch. Synonyms that rename a single branch are duplication — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
22	- Cut identity that's already in the body. Keep the description to triggers, plus any "when another skill needs…" reach clause.
23
24	## Information hierarchy
25
26	A skill is built from two content types — steps and reference — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the information hierarchy, a ladder ranked by how immediately the agent needs the material:
27
28	1. In-skill step — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a completion criterion, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites premature completion.
29	2. In-skill reference — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. _This skill is all reference._
30	3. External reference — reference pushed out of `SKILL.md` into a separate file, reached by a context pointer, loaded only when the pointer fires. (Spans _disclosed_ reference — a sibling file like `GLOSSARY.md`, still part of the skill — through fully external reference that lives outside the skill system and any skill can point at.)
31
32	A demanding completion criterion drives thorough legwork — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.
33
34	Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
35
36	Progressive disclosure is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a branch — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A context pointer's _wording_, not its target, decides when and how reliably the agent reaches the material.
37
38	Where the ladder decides _how far down_ a piece sits, **c

People who liked this also viewed

6 picks

Type

find-skillsHelps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skSkillsJul 20262.6M27k
grill-meA relentless interview to sharpen a plan or design.SkillsJul 2026633k182k
vercel-react-best-practicesVercel's official collection of agent skillsSkillsJul 2026573k29k
improve-codebase-architectureScan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.SkillsJul 2026522k182k
setup-matt-pocock-skillsConfigure this repo for the engineering skills — set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.SkillsJul 2026454k182k
triageMove issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs.SkillsJul 2026424k182k

writing-great-skills

59stars1forks

View on GitHub

How to install writing-great-skills?

rengwu/wayfinder-maps/writing-great-skills

$npx -y skills add rengwu/wayfinder-maps --skill writing-great-skills

Installs into the current project.

Summary

Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.

Files · 1

View on GitHub

SKILL.md

1	A skill exists to wrangle determinism out of a stochastic system. Predictability — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.
2
3	Bold terms are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning.
4
5	## Invocation
6
7	Two choices, trading different costs:
8
9	- A model-invoked skill keeps a description, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to context load — the description sits in the window every turn. Mechanics: mark it model-invoked in your harness's frontmatter (in most harnesses, simply keep the `description` and omit any `disable-model-invocation` flag), and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
10	- A user-invoked skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends cognitive load: _you_ are the index that must remember it exists. Mechanics: mark it user-invoked in your harness's frontmatter (`disable-model-invocation: true` where supported); the `description` becomes human-facing — a one-line summary, trigger lists stripped.
11
12	Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.
13
14	When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a router skill: one user-invoked skill that names the others and when to reach for each.
15
16	## Writing the description
17
18	A model-invoked description does two jobs — state what the skill is, and list the branches that should trigger it. Every word increases context load, so a description earns even harder pruning than the body:
19
20	- Front-load the skill's leading word — the description is where it does its invocation work.
21	- One trigger per branch. Synonyms that rename a single branch are duplication — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
22	- Cut identity that's already in the body. Keep the description to triggers, plus any "when another skill needs…" reach clause.
23
24	## Information hierarchy
25
26	A skill is built from two content types — steps and reference — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the information hierarchy, a ladder ranked by how immediately the agent needs the material:
27
28	1. In-skill step — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step ends on a completion criterion, the condition that tells the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it matters, _exhaustive_ ("every modified model accounted for", not "produce a change list") — a vague criterion invites premature completion.
29	2. In-skill reference — a definition, rule, or fact in `SKILL.md`, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. _This skill is all reference._
30	3. External reference — reference pushed out of `SKILL.md` into a separate file, reached by a context pointer, loaded only when the pointer fires. (Spans _disclosed_ reference — a sibling file like `GLOSSARY.md`, still part of the skill — through fully external reference that lives outside the skill system and any skill can point at.)
31
32	A demanding completion criterion drives thorough legwork — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.
33
34	Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
35
36	Progressive disclosure is the move down the ladder — out of `SKILL.md` into a linked file — so the top stays legible. Mechanics: a linked `.md` file in the skill folder, named for what it holds (this skill discloses its full definitions to `GLOSSARY.md`). Some skills are used in more than one way, and each distinct way is a branch — different runs taking different paths through the skill. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. A context pointer's _wording_, not its target, decides when and how reliably the agent reaches the material.
37
38	Where the ladder decides _how far down_ a piece sits, **c

People who liked this also viewed

6 picks

Type