agentleFS
luizomfluizomf/omskills/skills/productivity/writing-great-skills/SKILL.md

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

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.
  • FabienDehopreSkill

    decision-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

  • boyingliu01Skill

    batch-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

  • simo97Skill

    edit-article

    The user will invoke this skill to help them edit an article.

    Also in 18 projects that use this

  • simo97Skill

    request-refactor-plan

    Use this skill when user wants to create a refactor plan.

    Also in 17 projects that use this

  • RoentekSkill

    loop-me

    Grill me about specs for the workflows I want to build, within this workspace.

    Also in 19 projects that use this

  • LesaniSkill

    writing-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

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
  1. Very specific:

    Before applying a bold term below, read its complete definition and constraints in GLOSSARY.md.

    line 11
  2. Very specific:

    Use agent discovery only when observed use demonstrates a need for autonomous selection and a maintainer approves the permanent context …

    line 38
  3. Distinctive:

    When the user cannot recall the applicable user-only skill without inspecting or searching the list, recommend a user-only Router Skill.

    line 45
  4. Distinctive:

    place the skill's leading word before supporting detail.

    line 67
  5. Very specific:

    Use progressive disclosure by keeping content required by every branch in SKILL.md and moving branch-specific reference behind a pointer.

    line 97
  6. Distinctive:

    Keep each meaning in one single source of truth.

    line 121
  7. Distinctive:

    Test each sentence in isolation: if removing it would not change agent behavior, delete the complete sentence rather than rephrasing it.

    line 124
  8. Distinctive:

    Use a leading word when the established meaning of an existing pretrained concept preserves a repeated definition or set of qualities.

    line 129
  9. Distinctive:

    Sediment: delete content that no longer affects current skill behavior.

    line 151
  10. Distinctive:

    No-op: delete any sentence whose removal does not change behavior.

    line 154

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Ordered steps required during execution remain in SKILL.md.
  2. Definitions, rules, and facts needed by every branch may remain as in-skill reference.
  3. 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:

  1. Keep each meaning in one single source of truth.
  2. Retain a sentence only when it still affects the skill's process, branch selection, output, boundary, or completion criterion.
  3. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.