[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7887BDP2BC5HFHEKCNMBZ4Q":3,"skill-same:01M7887BDP2BC5HFHEKCNMBZ4Q":52},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":31,"ownerDescription":6,"updatedAt":32,"install":33,"resources":45},"01M7887BDP2BC5HFHEKCNMBZ4Q","writing-great-skills",null,"Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.","officialunofficial\u002Fskills","officialunofficial","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F127067914?v=4","01M78827JABEMMN63AC8J1RCXV","Official Unofficial, Inc.","01M78827KC164SFKN4DXTCKK7N",7,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fwriting-great-skills\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: writing-great-skills\ndescription: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.\ndisable-model-invocation: true\n---\n\nA skill exists to squeeze determinism out of a stochastic system. **Predictability** — the agent walking the same _process_ every run, not emitting the same output — is the root virtue; every lever below is in service of it.\n\n**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning.\n\n## Invocation\n\nTwo choices, each with its own cost:\n\n- A **model-invoked** skill keeps a **description**, so the agent can fire it on its own _and_ other skills can reach it (you can still type its name too). It carries **context load** — the description sits in the window every turn. Mechanics: leave off `disable-model-invocation`, and write a model-facing description with rich trigger phrasing (\"Use when the user wants…, mentions…\").\n- A **user-invoked** skill hides the description from the agent's reach: only you, typing its name, can fire it — and no other skill can. Zero context load, but it costs **cognitive load**: _you_ are the index that has to remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` turns human-facing — a one-line summary, trigger lists stripped.\n\nChoose 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.\n\nWhen user-invoked skills pile up past what you can hold in your head, that accumulated cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each.\n\n## Writing the description\n\nA model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word adds **context load**, so a description earns even harder pruning than the body:\n\n- **Lead with the skill's leading word** — the description is where it does its invocation work.\n- **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. Fold them together; keep only the branches that genuinely differ.\n- **Drop identity that's already in the body.** Hold the description to triggers, plus any \"when another skill needs…\" reach clause.\n\n## Information hierarchy\n\nA skill is built from two content types — **steps** and **reference** — that blend freely: a skill can be all steps, all reference, or both. The core call is which to use and where each lands on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:\n\n1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step closes on a **completion criterion**, the condition telling the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it counts, _exhaustive_ (\"every modified model accounted for\", not \"produce a change list\") — a vague criterion invites **premature completion**.\n2. **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._\n3. **External reference** — reference pushed out of `SKILL.md` into a separate file, reached by a **context pointer**, loaded only when the pointer fires. (Runs from _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.)\n\nA demanding completion criterion drives thorough **legwork** — the digging the agent does inside the work — whether the skill has steps or not, since \"every rule applied\" binds flat reference just as \"every step done\" binds a sequence.\n\nPush too little down and the top bloats; push too much and you bury material the agent actually needs. That tension is the whole call.\n\n**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.\n\nWhere the ladder settles _how far down_ a piece sits, **co-location** settles _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part pulls its neighbours in with it.\n\n## When to split\n\n**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut pays for itself. Two cuts:\n\n- **By invocation** — split off a **model-invoked** skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay **context load** for the new always-loaded **description**, so that independent reach has to earn it.\n- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it (**premature completion**). Keeping them out of view pushes the agent to do more **legwork** on the current task.\n\n## Pruning\n\nKeep each meaning in a **single source of truth**: one authoritative home, so changing the behaviour is a one-place edit.\n\nCheck every line for **relevance**: does it still bear on what the skill does?\n\nThen hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails it, delete the whole sentence rather than shave words off it. Be aggressive — most prose that fails should go, not be reworded.\n\n## Leading words\n\nA **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated across the text (though not always — a strong leading word may only be needed once), it accrues a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds.\n\nIt serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word shows up. In the description it anchors _invocation_: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably.\n\nHunt for chances to refactor skills onto leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to **collapse** into a single token. For example:\n\n- \"fast, deterministic, low-overhead\" → _tight_ — one quality restated across a phase — collapses into a single pretrained word (a _tight_ loop).\n- \"a loop you believe in\" → _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).\n\nYou win twice: fewer tokens, _and_ a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them.\n\n## Failure modes\n\nUse these to diagnose issues the user is having with a skill.\n\n- **Premature completion** — closing a step before it's genuinely done, attention slipping toward _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it's irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting (the sequence cut).\n- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.\n- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.\n- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs.\n- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique.\n- **Negation** — steering by prohibition backfires: _don't think of an elephant_ names the elephant and makes it more available, not less. Prompt the **positive** — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead.\n","A skill exists to squeeze determinism out of a stochastic system. **Predictability** — the agent walking the same _process_ every run, not emitting the same output — is the root virtue; every lever below is in service of it.\n\n**Bold terms** are defined in [`GLOSSARY.md`](GLOSSARY.md); look them up there for the full meaning.\n\n## Invocation\n\nTwo choices, each with its own cost:\n\n- A **model-invoked** skill keeps a **description**, so the agent can fire it on its own _and_ other skills can reach it (you can still type its name too). It carries **context load** — the description sits in the window every turn. Mechanics: leave off `disable-model-invocation`, and write a model-facing description with rich trigger phrasing (\"Use when the user wants…, mentions…\").\n- A **user-invoked** skill hides the description from the agent's reach: only you, typing its name, can fire it — and no other skill can. Zero context load, but it costs **cognitive load**: _you_ are the index that has to remember it exists. Mechanics: set `disable-model-invocation: true`; the `description` turns human-facing — a one-line summary, trigger lists stripped.\n\nChoose 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.\n\nWhen user-invoked skills pile up past what you can hold in your head, that accumulated cognitive load is cured by a **router skill**: one user-invoked skill that names the others and when to reach for each.\n\n## Writing the description\n\nA model-invoked **description** does two jobs — state what the skill is, and list the **branches** that should trigger it. Every word adds **context load**, so a description earns even harder pruning than the body:\n\n- **Lead with the skill's leading word** — the description is where it does its invocation work.\n- **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. Fold them together; keep only the branches that genuinely differ.\n- **Drop identity that's already in the body.** Hold the description to triggers, plus any \"when another skill needs…\" reach clause.\n\n## Information hierarchy\n\nA skill is built from two content types — **steps** and **reference** — that blend freely: a skill can be all steps, all reference, or both. The core call is which to use and where each lands on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:\n\n1. **In-skill step** — an ordered action in `SKILL.md`, the primary tier: what the agent does, in order. Each step closes on a **completion criterion**, the condition telling the agent the work is done. Make it _checkable_ (can the agent tell done from not-done?) and, where it counts, _exhaustive_ (\"every modified model accounted for\", not \"produce a change list\") — a vague criterion invites **premature completion**.\n2. **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._\n3. **External reference** — reference pushed out of `SKILL.md` into a separate file, reached by a **context pointer**, loaded only when the pointer fires. (Runs from _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.)\n\nA demanding completion criterion drives thorough **legwork** — the digging the agent does inside the work — whether the skill has steps or not, since \"every rule applied\" binds flat reference just as \"every step done\" binds a sequence.\n\nPush too little down and the top bloats; push too much and you bury material the agent actually needs. That tension is the whole call.\n\n**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.\n\nWhere the ladder settles _how far down_ a piece sits, **co-location** settles _what sits beside it_ once there: keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part pulls its neighbours in with it.\n\n## When to split\n\n**Granularity** is how finely you divide skills, and each cut spends one of the two loads, so split only when the cut pays for itself. Two cuts:\n\n- **By invocation** — split off a **model-invoked** skill when you have a distinct **leading word** that should trigger it on its own, or another skill must reach it. You pay **context load** for the new always-loaded **description**, so that independent reach has to earn it.\n- **By sequence** — split a run of **steps** when the steps still ahead (a step's **post-completion steps**) tempt the agent to rush the one in front of it (**premature completion**). Keeping them out of view pushes the agent to do more **legwork** on the current task.\n\n## Pruning\n\nKeep each meaning in a **single source of truth**: one authoritative home, so changing the behaviour is a one-place edit.\n\nCheck every line for **relevance**: does it still bear on what the skill does?\n\nThen hunt **no-ops** sentence by sentence, not just line by line: run the no-op test on each sentence in isolation, and when one fails it, delete the whole sentence rather than shave words off it. Be aggressive — most prose that fails should go, not be reworded.\n\n## Leading words\n\nA **leading word** is a compact concept already living in the model's pretraining that the agent thinks with while running the skill (e.g. _lesson_, _fog of war_, _tracer bullets_). Repeated across the text (though not always — a strong leading word may only be needed once), it accrues a distributed definition and anchors a whole region of behaviour in the fewest tokens, by recruiting priors the model already holds.\n\nIt serves predictability twice. In the body it anchors _execution_: the agent reaches for the same behaviour every time the word shows up. In the description it anchors _invocation_: when the same word lives in your prompts, docs, and code, the agent links that shared language to the skill and fires it more reliably.\n\nHunt for chances to refactor skills onto leading words. A triad spelled out at three sites (**duplication**), a description spending a sentence to gesture at one idea — each is a passage begging to **collapse** into a single token. For example:\n\n- \"fast, deterministic, low-overhead\" → _tight_ — one quality restated across a phase — collapses into a single pretrained word (a _tight_ loop).\n- \"a loop you believe in\" → _red_ — converts a fuzzy gate into a binary observable state (the loop goes _red_ on the bug, or it doesn't).\n\nYou win twice: fewer tokens, _and_ a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them.\n\n## Failure modes\n\nUse these to diagnose issues the user is having with a skill.\n\n- **Premature completion** — closing a step before it's genuinely done, attention slipping toward _being done_. Defence, in order: sharpen the completion criterion first (cheap, local); only if it's irreducibly fuzzy _and_ you observe the rush, hide the post-completion steps by splitting (the sequence cut).\n- **Duplication** — the same meaning in more than one place. Costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.\n- **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.\n- **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs.\n- **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique.\n- **Negation** — steering by prohibition backfires: _don't think of an elephant_ names the elephant and makes it more available, not less. Prompt the **positive** — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead.\n",{"name":5,"description":7,"disable-model-invocation":24},true,"main","e1e71e8aa302edca3e052370aefa9272f86d07ee","skills\u002Fproductivity\u002Fwriting-great-skills",0,"https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills","https:\u002F\u002Fgithub.com\u002Fofficialunofficial","officialunofficial.com","2026-11-06 10:07:10",{"source":8,"skillName":5,"commands":34,"prompt":44,"zipAvailable":24},[35,38,41],{"tool":36,"command":37},"npx","npx skills add officialunofficial\u002Fskills --skill writing-great-skills",{"tool":39,"command":40},"bunx","bunx skills add officialunofficial\u002Fskills --skill writing-great-skills",{"tool":42,"command":43},"pnpm","pnpm dlx skills add officialunofficial\u002Fskills --skill writing-great-skills","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fwriting-great-skills\u002FSKILL.md",[46],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"GLOSSARY.md","REFERENCE","参考文档",18455,"https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fwriting-great-skills\u002FGLOSSARY.md",[53,60,67,74,81,88],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M788772K4QYXCZX3Y2P2AX9V","technical-writing","House style for technical writing — the voice, sentence craft, formatting, and user-facing-copy rules that make docs and product text clear, direct, and consistent. Use when writing or editing a README, docs, a spec, release notes, a changelog, help text, or any error\u002FCLI\u002FUI copy a person reads; when reviewing a diff that touches prose or messages; or when a project needs a writing standard. Reference-heavy mechanics live in REFERENCE.md.","https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Ftechnical-writing\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M78875087F1XKP7C6VRC49CY","teach","Teach the user a new skill or concept, within this workspace.","https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fteach\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M78872Z38MACN22AQDY9410P","handoff","Compact the current conversation into a handoff document for another agent to pick up.","https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fhandoff\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M78870FVRDYRT1WVP9HJ6FQ3","grilling","Interrogate the user's plan or design one decision at a time until you both share the same understanding. Use when the user wants to pressure-test an idea before building it, or reaches for any 'grill' trigger phrase.","https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fgrilling\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M7886XGPEWXZYDA6K310HNYP","grill-me","A relentless, one-decision-at-a-time interview that sharpens a plan or design.","https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fproductivity\u002Fgrill-me\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M7886RR14H806M0GMNYX2BCV","setup-pre-commit","Add a Husky pre-commit hook backed by lint-staged (Prettier), plus type checking and tests, to the current repo. Use when the user wants pre-commit hooks, wants to set up Husky or lint-staged, or wants Prettier, typecheck, and tests to run at commit time.","https:\u002F\u002Fgithub.com\u002Fofficialunofficial\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fmisc\u002Fsetup-pre-commit\u002FSKILL.md",[],[]]