writing-great-skills

Provides vocabulary and principles for writing predictable, well-structured AI agent skills.

1|Updated Jul 23, 2026
One-click install
npx skills add https://github.com/sanjanb/my-agent-harness --skill writing-great-skills-sanjanb
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: writing-great-skills
Source: https://github.com/sanjanb/my-agent-harness/tree/main/skills/mp-writing-great-skills
Command: npx skills add https://github.com/sanjanb/my-agent-harness --skill writing-great-skills-sanjanb

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Writing SKILL.md files that make an AI agent behave consistently is hard: descriptions misfire, instructions bloat, and agents rush steps or ignore guidance. This Skill supplies a shared vocabulary and decision framework for authoring and editing skills so the agent follows the same process every run. ## Core Features & Use Cases - Invocation design: Decide between model-invoked and user-invoked skills by weighing context load against cognitive load, and configure disable-model-invocation accordingly. - Information hierarchy: Arrange steps, in-file reference, and disclosed reference behind context pointers, using progressive disclosure and co-location to keep SKILL.md legible. - Failure-mode diagnosis: Identify and fix premature completion, duplication, sediment, sprawl, no-ops, and negation in existing skills. - Use Case: When a skill you wrote fires unreliably or the agent skips work, invoke this Skill to audit its description wording, completion criteria, and leading words against the glossary in GLOSSARY.md. ## Quick Start Ask the agent to review your SKILL.md using the writing-great-skills principles and suggest concrete edits to its description and structure.

Frequently Asked Questions about writing-great-skills

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a good skill description for an AI agent?

Front-load the skill's leading word and list one trigger per distinct branch, since every word adds permanent context load. Cut synonyms that rename a single branch and remove identity statements already covered in the skill body.

When should a skill be model-invoked vs user-invoked?

Choose model-invoked only when the agent or another skill must reach it autonomously, accepting the context load of an always-loaded description. If it only ever fires by hand, set disable-model-invocation: true and pay zero context load.

How do I stop an agent from rushing through skill steps?

Sharpen each step's completion criterion first so done is clearly checkable, since a sharp bound resists the pull of visible later steps. Only if the criterion is irreducibly fuzzy and rushing persists, split the sequence to hide post-completion steps.

What is progressive disclosure in skill writing?

Progressive disclosure moves reference material out of SKILL.md into linked files reached via context pointers, keeping the top of the file legible. Inline what every branch needs and disclose what only some branches reach.

Why should I avoid negative instructions in prompts and skills?

Prohibitions drag the forbidden behavior into context and make it more available, so the ban half-reads as an instruction. State the positive target behavior instead, reserving negation for hard guardrails paired with what to do instead.