agentleFS
sgaabdu4sgaabdu4/appwrite-backend/.agents/skills/writing-great-skills/SKILL.md

writing-great-skills

Skill2 starsChanged 4 days agoMITView on GitHub

Write, revise or review an agent skill (SKILL.md package).

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

Files
SKILL.md

Writing Great Skills

  • Scope = user request + settled constraints + existing authorization; skill adds no authority.
  • Agent prose = minimum tokens + unambiguous meaning. Use =, →, +, terse bullets/tables where clear; delete filler + repetition. Preserve conditions, actions, exceptions and proof; cryptic abbreviations ≠ useful compression.

Routes

Load matching routes only; Core always applies.

flowchart LR
  C[Core] -->|Package / metadata / invocation| P[references/package.md]
  C -->|Observed skill failure| R[references/repair.md]
  click P "references/package.md"
  click R "references/repair.md"

Core

CheckRequired outcome
NeedRemoval loses reusable, non-default behavior; omit generic agent advice.
TriggerPurpose + distinct use; relevant prompts match, unrelated prompts do not. Preserve implicit selection unless user requests explicit-only.
DisclosureSKILL.md = routes + essential shared rules. Conditional workflows/examples/detail → references. Each route = load condition + direct link; load only applicable routes. Keep short universal rules inline.
DiagramFlow, decision, state or dependency → Mermaid by default. Terse labels; one representation, no prose duplicate. Non-relational rule → bullet/table.
SplitSame actions + proof → keep together. Split for independent use or observed failure unresolved by clearer completion.
ResourceScript = repeated fragile logic; reference = conditional knowledge; asset = copied output. Each needs a current consumer; no mandatory file count.
OwnershipRule + definition + caveat = one owner. Inspect package + relevant siblings/project instructions; consolidate duplicates + remove stale rules.
SteeringState target action + observable completion; likely mistake → replacement action.
ReaderAfter new or rewritten prose, a subagent that did not write it compares the old and new text. It quotes each sentence it had to reread and each sentence whose meaning changed. Fix each quoted sentence by rewording it or moving it to a reference. Do not cut more words: here clarity beats minimum tokens. The subagent reads each changed sentence with its paragraph or table row, and reads each restructured file in full.
ValidationAvailable native validator + changed links/tools/skills exist + metadata agrees. Substantial/risky change → representative trigger/non-trigger prompts + actual outcome proof. Run changed scripts; wording tests ≠ behavior proof.

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.