agentleFS
Sign inStart free
imMamdouhaboammarimMamdouhaboammar/matts-skills-into-chatgpt/skills/writing-for-agents/SKILL.md

writing-for-agents

Skill8 starsChanged 2 months agoMITView on GitHub

Author and refine agent-facing instructions, skills, AGENTS.md files, and context pointers. Use when creating new agent skills, optimizing prompt guidelines, writing steerable docs, or organizing progressive disclosure — even if the user says \"write a skill for this\". Do NOT use for human-facing marketing copy.

We split this skill into the rules it gives an agent

4 rules. 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 173 edited versions we read keep these.

  • 4

    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
  1. Distinctive:

    Observable Completion Criteria: Every step must conclude on a checkable, exhaustive completion bound to prevent premature victory …

    line 17
  2. Distinctive:

    Key Point: Never put workflow steps inside the pointer or description.

    line 51
  3. Distinctive:

    Why: When process steps appear in the description, models follow them and skip the detailed body.

    line 52
  4. Distinctive:

    Key Point: Keep the main file under 500 lines.

    line 56

“Common” is measured: kept by at least 6 in 10 of the 173 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

Writing for Agents

Author and refine documents an agent consumes: a Skill, an AGENTS.md / CLAUDE.md, or a document reached by a context pointer. The packaging differs; the writing principles do not.

Core Invariants

  1. The 10 Authoring Principles: Adhere strictly to pre-flight checks, zero process in descriptions, MOC architecture (< 500 lines), TWI clarity, inline checklists, one term per concept, zero hardcoded secrets, and matching form to failure.
  2. Context Load vs. Cognitive Load: Inline what every branch needs; push behind context pointers what only some branches reach.
  3. Front-Loaded Leading Words: Recruit model priors with precise tokens (tight, red, tracer bullets) rather than lengthy re-explanations.
  4. Observable Completion Criteria: Every step must conclude on a checkable, exhaustive completion bound to prevent premature victory declaration.
  5. Zero Process in Descriptions: Descriptions define triggering boundaries (Use when..., Do NOT use for...), never workflow recipes.

Architecture & Map of Content (MOC)

[ Context Pointer / Description ] ──► [ SKILL.md: Map of Content ] ──► [ Disclosed References / Scripts ]
DomainKey MechanismReference
Context PointersTrigger condition + branch definitionreferences/pointers.md
Information HierarchyIn-file step → In-file reference → Disclosed referenceSKILL-MECHANICS.md
Progressive DisclosureKeep SKILL.md < 500 lines; push heavy specs outskill-conductor
Skill LifecycleDraft → Test → Review → Improve → Packageskill-conductor

The Information Hierarchy

A document is built from steps (ordered actions) and reference (definitions and rules):

  1. In-file step: The primary tier — what the agent does, in order.
  2. In-file reference: Consulted on demand; short tables or checklists co-located with steps.
  3. Disclosed reference: Pushed into a separate file reached by a pointer, loaded only when that branch fires.

Step-by-Step Procedure (TWI)

Step 1: Design Context Pointers & Trigger Boundaries

  • Action: Draft the pointer with front-loaded leading words, distinct trigger branches, and explicit negative exclusions.
  • Key Point: Never put workflow steps inside the pointer or description.
  • Why: When process steps appear in the description, models follow them and skip the detailed body.

Step 2: Structure the Body as a Map of Content

  • Action: Organize the main markdown file as an executive map with concise headings, TWI steps, and inline checklists.
  • Key Point: Keep the main file under 500 lines; disclose deep schemas into reference files.
  • Why: Attention thins across overly long documents, causing instructions to be skipped.

Step 3: Define Checkable Completion Bounds

  • Action: Conclude every procedure with an unambiguous completion criterion.
  • Inline Checklist:
    • Frontmatter name is kebab-case and matches folder
    • Description has positive triggers and negative exclusions (Do NOT use for...)
    • Main document is under 500 lines
    • No hardcoded secrets, API tokens, or user home paths
  • Why: Clear bounds prevent premature step termination and unverified assumptions.

Anti-Rationalization Guardrails

Tempting RationalizationBinding RuleEngineering Rationale
"I'll list the steps in the description so it triggers better."Forbidden: descriptions define triggers, not steps.Models execute the summary description and skip the detailed body instructions.
"More documentation is always better."Prune aggressively: ruthlessly eliminate no-ops.Excess lines dilute attention and increase cognitive and context load.
"I can use 'MUST' in all caps instead of explaining why."Explain the reasoning (TWI: Action, Key Point, Why).Explaining why produces robust generalization; rigid prohibitions invite prompt injection.
"Keep everything in one file for convenience."Progressive disclosure: disclose heavy references.Single-file sprawl degrades context efficiency and task focus.

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.

Check your setup, free