writing-great-skills
Skill0 starsChanged 3 months agoMITView on GitHub
Author, revise, and finish agent skills — the authoring path, vocabulary, and finishing checks that make a skill predictable.
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 6 projects that use this
simo97Skilledit-article
The user will invoke this skill to help them edit an article.
Also in 19 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
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 21 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
- +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.7ksame name
- Aniket-508/termcn★ 1.2ksame name
- stevesolun/ctx★ 583same name
- aws/graph-explorer★ 492same name
- Akylas/oss-weather★ 485same 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 repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- codebase-designSkill
- code-reviewSkill
- commission-method-gap-researchSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- grillingSkill
- grill-with-docsSkill
- handoffSkill
- implementSkill
- improve-codebase-architectureSkill
- method-gap-research-statusSkill
- prototypeSkill
- refactor-skillSkill
- research-briefSkill
- researchSkill
- setup-matt-pocock-skillsSkill
- skill-evidence-captureSkill
- skill-evolutionSkill
- skill-evolution-statusSkill
- tddSkill
- teachSkill
- to-issuesSkill
- to-prdSkill
- triageSkill
- wait-whatSkill
- wayfinderSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 8 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 99 edited versions we read keep these.
8
Distinctive
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
When another skill dispatches this one, treat its exact source, logical and physical target, authority boundary, preservation envelope, …
- Distinctive: line 31
If a load-bearing input does not exist yet, stop at a bounded dependency stub or handoff that names what is missing, what remains …
- Distinctive: line 50
Use three content forms deliberately:
- Distinctive: line 66
Keep each meaning in one authoritative place.
- Distinctive: line 70
Check each sentence for:
- Distinctive: line 87
Verify the completed package against the current repository:
- Distinctive: line 92
Read the package end to end for coherent order, complete sentences, stable numbering, and preserved public outputs.
- Distinctive: line 93
Run applicable repository checks, mirror checks, and other completion contracts from root guidance.
“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
Writing Great Skills
A skill makes a stochastic agent predictable by stabilizing its process, not its wording or output. Use this reference to author a new skill or revise an existing one.
Arguments: an optional directive, source artifact, precedent, or target skill. Without one, use the conversation's request.
Within skill-evidence, this skill and current repository guidance are the authoring authority. Treat bundled or other generic skill-authoring instructions as supplementary only where compatible. Never let their default location, initializer, frontmatter allowlist, or validator override the authorized target or write set, .claude/skills/ ownership, .agents/skills/ discovery links, client-specific invocation metadata, or repository-native checks; report the mismatch as a compatibility finding.
When another skill dispatches this one, treat its exact source, logical and physical target, authority boundary, preservation envelope, invocation reach, and write set as binding authoring inputs. Author only within that write set and return the file inventory, preservation mapping, unresolved dependencies, pointers, client fields, and checks the caller requested. Do not perform the caller's source deletion, transaction edits, or canonical adoption unless the dispatch explicitly assigns them.
Authoring path
1. Establish evidence and the local contract
When a routine has run before, read the named reports, sessions, artifacts, and closest applicable sibling before drafting. Separate stable behavior, vocabulary, file shapes, and ordering from run-specific inputs. From a sibling skill, import only moves that share the new skill's decision surface; source-specific mechanics stay behind.
For an existing skill, inventory and read its complete package before changing it. Map its triggers, branches, safety rules, arguments, outputs, context pointers, instruments, and client metadata so restructuring cannot silently drop behavior.
Check root guidance and the current skill standard, loader, or local validator when frontmatter, discovery, packaging, or layout is involved. If the repository has no authoritative check, use a known-loading same-mode sibling as evidence for client-facing fields and policy files. A generic validator that rejects the same repository-native contract on that sibling is a compatibility finding, not authority to delete required fields.
If a load-bearing input does not exist yet, stop at a bounded dependency stub or handoff that names what is missing, what remains invariant, and what event allows authoring to resume.
Done when the available evidence and applicable repository contract are recorded, stable conventions are separated from input, and no required design input is being guessed.
2. Settle scope, invocation, and description
Settle only forks that change what ships. Use evidence where it decides; otherwise recommend one option with its consequence and ask for the user's ruling. Do not turn cosmetic preference into a gate.
Choose invocation by reach:
- A model-invoked skill is visible for autonomous selection and dispatch from other skills. Its description names what it does and one trigger per material branch; prune trigger synonyms and body identity.
- A user-invoked skill is reached explicitly by the human. Its description is a short human-facing identity, and every client surface the repository ships must encode the same explicit-only choice. Put argument expectations in the body or supported metadata rather than assuming one universal field.
Model reach spends context load in always-visible metadata; explicit reach spends cognitive load because the human must remember the skill. If many explicit-only skills become hard to find, a small router can name them and provide ready invocation lines, but it cannot implicitly fire an explicit-only target.
Done when scope, arguments, invocation mode, trigger branches, and every outcome-changing fork are explicit and mutually consistent across shipped client surfaces.
3. Draft the smallest executable shape
Use three content forms deliberately:
- Steps are ordered actions in
SKILL.md. End each with a completion criterion that is checkable and demanding enough to force the needed legwork. - Reference is consulted on demand. Inline what every branch needs; put lengthy or branch-only material behind a context pointer that says when to load it and what to do with it. Default new supporting prose to
references/<topic>.md, subject to the current standard and an established house-form exception. Co-locate each concept's rules and caveats. - An instrument is an executable check, extraction, or transformation under the repository's script convention. Point to it and run it; do not inline it as prose.
These forms sit on an information hierarchy ranked by how immediately the agent needs the material: in-file step, then in-file reference, then reference disclosed behind a pointer. Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole placement decision.
A branch is a materially different valid route through the skill. Use branch need, not a line threshold, to decide disclosure. Split into another invocable skill only when it needs independent reach. Split a sequence only after an observed premature-completion problem survives a sharper completion criterion, and only across a real context boundary.
Draft from the evidence gathered in step 1. Keep safety invariants, output contracts, and ownership boundaries visible at the point where they constrain action. When revising, preserve every mapped behavior unless the request explicitly authorizes a change.
Done when every action has an observable bound, every branch reaches exactly the material it needs, every pointer has a target and condition, and the package contains no unsupported behavior change.
4. Prune the package
Keep each meaning in one authoritative place. An output that must stand alone may repeat necessary instructions; the skill itself should point rather than duplicate.
The environment is a source of truth too — script definitions, config files, the directory layout, --help output — and a skill that restates it is a cache: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses.
Check each sentence for:
- Relevance — it still bears on this skill and its current environment.
- Duplication — the same instruction has another authoritative home.
- Sediment — an old layer remains only because removal feels risky.
- Sprawl — live reference crowds the common path and belongs behind a branch pointer.
- No-op — removing it would not change agent behavior.
- False premise — an empirical rule has not reproduced in the current environment.
A leading word can compress repeated explanation when a familiar concept genuinely steers behavior; it is useful only if it changes the process more reliably than the prose it replaces.
Negation is the failure mode beside that lever: steering by prohibition drags the forbidden behavior into context and makes it more available, not less — the ban half-reads as an instruction to do the thing. Prompt the positive: state the target behavior so the banned one is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively, and even then it is paired with the positive target.
Done when every remaining instruction has one home and a behavioral reason to remain, with uncertain domain knowledge retained rather than deleted by intuition.
5. Finish and prove it
Verify the completed package against the current repository:
- Parse and load its frontmatter and every client-facing policy surface; confirm the chosen invocation mode and arguments work as intended.
- Resolve every context pointer. For a sibling-skill dispatch, also confirm reachability; hand the human a ready invocation when the target is explicit-only.
- Execute every instrument and reproduce every empirical environment claim against a real or inert representative target.
- Read the package end to end for coherent order, complete sentences, stable numbering, and preserved public outputs.
- Run applicable repository checks, mirror checks, and other completion contracts from root guidance.
Forward-test in a fresh independent context when the skill has material branches, relies on non-obvious judgment, or changed substantially. Give the test the skill plus representative raw input, not the diagnosis or expected winner; record the expected process before the run and compare actual decisions and artifacts. Keep the test read-only or in scratch space unless the user authorizes realistic effects. A timeout, leaked setup, unexercised material branch, or missing result is not a pass.
A fresh context is not automatically source-blind. When a comparison or claim requires source-blindness, follow Source-blind forward tests to make implicit startup context part of the isolation boundary and audit it. Do not impose that harness on an ordinary independent forward test that makes no source-blind claim.
Done when all applicable checks pass, every material branch and invariant has proportionate evidence, and no unresolved failure is reported as completion.
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.

