writing-great-skills
Skill3 starsChanged 2 months agoMITView on GitHub
Optimize each skill for predictability: repeated runs should follow the same process, although their outputs may differ. Before applying a bold term below, read its complete definition and constraints in GLOSSARY.md. Choose one discovery mode: - Agent-discoverable: omit disable-model-invocation. The required description remains in system context and allows autonomous selection, adding context load. - User-only: set disable-model-invocation: true. The description remains command-facing metadata but is excluded from system context. The user selects the skill, adding cognitive load instead of context…
104 other projects use a version of this.
Adopted by
Most recently taken up by
- Kcalb0708/claude_skillstheir own version, first seen Nov 16, 2026
- richard12511/claude-skillstheir own version, first seen Nov 16, 2026
- lhotwll217/owner-operatortheir own version, first seen Nov 16, 2026
- sgaabdu4/appwrite-backendtheir own version, first seen Nov 13, 2026
- matheus3006/my-claude-skillstheir own version, first seen Nov 8, 2026
- LeonardiFranco/skillstheir own version, first seen Nov 8, 2026
Used with
Projects with it also use decision-mapping, batch-grill-me and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
FabienDehopreSkilldecision-mapping
Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time.
Also in 7 projects that use this
boyingliu01Skillbatch-grill-me
A relentless interview that asks every frontier question at once, round by round. Thin alias of `grilling` (#540) — upstream mattpocock/skills absorbed this protocol into grilling; XP-Gate keeps this name as the sprint-flow Phase 2 entry point so orchestration docs stay stable.
Also in 7 projects that use this
simo97Skilledit-article
The user will invoke this skill to help them edit an article.
Also in 18 projects that use this
simo97Skillrequest-refactor-plan
Use this skill when user wants to create a refactor plan.
Also in 17 projects that use this
RoentekSkillloop-me
Grill me about specs for the workflows I want to build, within this workspace.
Also in 19 projects that use this
LesaniSkillwriting-shape
Take a markdown file of raw material and shape it into an article through a conversational session — drafting candidate openings, growing the piece paragraph by paragraph, arguing about format (lists, tables, callouts, quotes) at each step. Use when the user has a pile of notes, fragments, or a rough draft and wants help turning it into something publishable.
Also in 20 projects that use this
- +3 more from simo97
Other versions104 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 104
- GreyDGL/PentestGPT★ 16ksame name
- Akylas/OSS-DocumentScanner★ 2.6ksame name
- Aniket-508/termcn★ 1.2ksame name
- stevesolun/ctx★ 583same name
- aws/graph-explorer★ 492same name
- Akylas/oss-weather★ 478same name
- sveltejs/ai-tools★ 337same name
- sveltejs/mcp★ 337same name
- ninehills/skills★ 280same name
- loulanyue/skills★ 231same name
94 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository31 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- codebase-designSkill
- code-reviewSkill
- diagnosing-bugsSkill
- dispatch-ticketsSkill
- grill-with-docsSkill
- implementSkill
- improve-codebase-architectureSkill
- orchestrateSkill
- prototypeSkill
- researchSkill
- resolving-merge-conflictsSkill
- setup-omskillsSkill
- tddSkill
- to-specSkill
- to-ticketsSkill
- triageSkill
- wayfinderSkill
- cavemanSkill
- designSkill
- excalidrawSkill
- grill-meSkill
- handoffSkill
- model-routingSkill
- prompt-comprehension-auditsSkill
- teachSkill
- tmux-workerSkill
- voiceSkill
- wormholeSkill
- write-a-skillSkill
The file
We split this skill into the rules it gives an agent
10 rules. 0 are common, 7 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 99 edited versions we read keep these.
7
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Before applying a bold term below, read its complete definition and constraints in GLOSSARY.md.
- Very specific: line 38
Use agent discovery only when observed use demonstrates a need for autonomous selection and a maintainer approves the permanent context …
- Distinctive: line 45
When the user cannot recall the applicable user-only skill without inspecting or searching the list, recommend a user-only Router Skill.
- Distinctive: line 67
place the skill's leading word before supporting detail.
- Very specific: line 97
Use progressive disclosure by keeping content required by every branch in SKILL.md and moving branch-specific reference behind a pointer.
- Distinctive: line 121
Keep each meaning in one single source of truth.
- Distinctive: line 124
Test each sentence in isolation: if removing it would not change agent behavior, delete the complete sentence rather than rephrasing it.
- Distinctive: line 129
Use a leading word when the established meaning of an existing pretrained concept preserves a repeated definition or set of qualities.
- Distinctive: line 151
Sediment: delete content that no longer affects current skill behavior.
- Distinctive: line 154
No-op: delete any sentence whose removal does not change behavior.
“Common” is measured: kept by at least 6 in 10 of the 99 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Optimize each skill for predictability: repeated runs should follow the same process, although their outputs may differ.
Before applying a bold term below, read its complete definition and constraints
in GLOSSARY.md.
Discovery
Choose one discovery mode:
- Agent-discoverable: omit
disable-model-invocation. The required description remains in system context and allows autonomous selection, adding context load. - User-only: set
disable-model-invocation: true. The description remains command-facing metadata but is excluded from system context. The user selects the skill, adding cognitive load instead of context load.
A loaded skill may compose a user-only skill through a context pointer that
links directly to its file and states the condition for reading it. Use relative
Markdown paths for bundled and cross-skill references. Give each composing skill
an executable resolution step:
python3 -c 'from pathlib import Path; import sys; print((Path(sys.argv[1]).resolve().parent / sys.argv[2]).resolve())' '<loaded-file-path>' '<relative-link>'.
Substitute the actual loaded file and link, run it, then read the printed path.
Resolve the source symlink before applying ..; lexical normalization against
the installation path is not physical resolution. Read the linked file even when
its skill is absent from the discovery list; report unavailability only after
checking the target. When forwarding a pointer to a fresh agent, resolve it
first and include the resulting path in the prompt. Keep machine-specific
absolute paths out of distributed files.
Use agent discovery only when observed use demonstrates a need for autonomous selection and a maintainer approves the permanent context load. Existing agent-discoverable omskills have met both conditions. Active status is independent: active user-only skills remain installed for direct selection without permanent context load, and every new skill remains user-only until promoted.
When the user cannot recall the applicable user-only skill without inspecting or
searching the list, recommend a user-only Router Skill; create it only when
the accepted scope authorizes that addition. Its context pointers must link each
target and state the condition for reading it. This is a skill-selection role
only. Mission continuity belongs to dispatch-tickets when used.
For skills that route execution, keep an untracked request or one selected
Ticket with its current conversational owner. implement loads orchestrate in
that conversation; orchestrate is the owner's delivery procedure, not a
separate coordinator. Maintainer absence changes how unresolved Questions are
handled, not ownership or topology, and adds no audit or approval gate by
itself. Continue through the authorized stopping point. A dispatcher supervises
multiple selected Tickets: queue, relations, order, time/progress, and verified
delivery, without writing code. New dispatched Tickets get fresh owners;
existing work keeps its owner. Discovery selects the skill; the accepted request
selects the work and applicable gates.
Descriptions
For an agent-discoverable description:
- state the capability;
- place the skill's leading word before supporting detail;
- include exactly one trigger for each distinct branch;
- collapse synonyms that trigger the same branch;
- omit identity or process details already present in the body;
- retain a reach clause such as "when another skill needs..." only when it enables composition.
For a user-only description, write a command-facing capability summary and omit automatic trigger phrasing.
Information Hierarchy
Classify content as steps or reference and place it on this hierarchy:
- Ordered steps required during execution remain in
SKILL.md. - Definitions, rules, and facts needed by every branch may remain as in-skill reference.
- Reference needed by only some branches moves behind a context pointer to a disclosed file or an external artifact.
A flat set of peer rules is valid reference and does not require artificial sequencing.
End every step with a completion criterion that the agent can evaluate as true or false. When the task requires coverage, quantify the criterion over all required items, for example, "every modified model is accounted for." Apply an equivalent exhaustive criterion to flat reference when every rule must be checked. The criterion must require the legwork needed to satisfy every quantified item.
Use progressive disclosure by keeping content required by every branch in
SKILL.md and moving branch-specific reference behind a pointer.
Within a file, apply co-location: put each concept's definition, rules, and exceptions under one heading.
When to Split
Split only under one of these conditions:
- By discovery: the new skill has a distinct leading word that should trigger autonomous selection, and its discovery has met the approval condition above. Explicit composition alone requires a context pointer, not a discoverable skill.
- By sequence: an observed run ends a step early because visible post-completion steps pull attention forward, and the current completion criterion cannot be made checkable. Place the later steps across a fresh-context boundary; loading another skill in the same conversation does not hide them.
Pruning
Apply these checks sentence by sentence:
- Keep each meaning in one single source of truth.
- Retain a sentence only when it still affects the skill's process, branch selection, output, boundary, or completion criterion.
- Test each sentence in isolation: if removing it would not change agent behavior, delete the complete sentence rather than rephrasing it.
Leading Words
Use a leading word when the established meaning of an existing pretrained concept preserves a repeated definition or set of qualities. Repeat the word where it anchors execution or discovery; do not repeat its full definition.
Inspect every skill for meanings restated in multiple places. Replace a restatement with a leading word only when the replacement preserves all conditions and distinctions. Examples:
- replace "fast, deterministic, low-overhead" with tight only when tight is defined to preserve all three requirements;
- replace "a loop you believe in" with red when the required criterion is that the loop demonstrably fails on the bug.
Failure Modes
Diagnose and correct each observed failure as follows:
- Premature completion: first make the completion criterion checkable. Split the sequence across a fresh context only when the criterion cannot be made checkable and an observed run still ends the step early.
- Duplication: retain one authoritative statement of the meaning and replace intentional recurrence with a leading word.
- Sediment: delete content that no longer affects current skill behavior.
- Sprawl: move branch-specific reference behind context pointers; apply When to Split only if a split is still needed.
- No-op: delete any sentence whose removal does not change behavior. If a leading word is too weak to change behavior, replace it with a word that imposes an observable criterion, such as red, or remove it.
- Negation: state the required positive behavior. Retain a prohibition only for a hard boundary that has no equivalent positive formulation, and pair it with the required alternative.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

