writing-skills

Guides creation and editing of reusable agent skill documentation with trigger-focused descriptions.

Updated Jul 22, 2026

Search Tags:#tdd #documentation #claude skills #prompt design #skill authoring #frontmatter #agent instructions

Ready to run

npx skills add https://github.com/jeremylightsmith/relay-config --skill writing-skills-jeremylightsmith

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: writing-skills
Source: https://github.com/jeremylightsmith/relay-config/tree/main/.claude/skills/writing-skills
Command: npx skills add https://github.com/jeremylightsmith/relay-config --skill writing-skills-jeremylightsmith

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Agents often write skills that summarize workflows in the description field, causing other agents to follow the summary and skip the actual instructions. This Skill teaches how to write skills that agents correctly discover, load, and apply. ## Core Features & Use Cases - Description discipline: Enforces trigger-only descriptions starting with "Use when…" so agents load the skill body instead of following a summary. - TDD-style skill authoring: Pressure-test an agent without the skill (RED), write the skill to fix observed failures (GREEN), then close remaining loopholes (REFACTOR). - Structure and brevity rules: Defines frontmatter fields, body sections, word-count targets, and cross-referencing conventions for concise, reusable skills. - Use Case: When creating a new skill for test-driven development, use this guide to write a description with concrete triggers and a tight body that agents reliably follow. ## Quick Start Use the writing-skills skill to review my new skill draft and fix its description and structure.

Frequently Asked Questions about writing-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?▼

Write only triggering conditions starting with "Use when…", in third person, with concrete symptoms and searchable keywords. Never summarize the workflow, because agents will follow the summary and skip the skill body.

How to test whether a new agent skill actually works?▼

Apply TDD to documentation: run an agent without the skill and watch it fail (RED), write the skill addressing those failures (GREEN), then close remaining loopholes (REFACTOR). Without observing failure, you cannot know the skill teaches the right thing.

When should I not create a new skill?▼

Skip skills for one-off solutions, standard practices documented elsewhere, project-specific conventions (those belong in AGENTS.md), and anything a linter or regex check can enforce mechanically.

What frontmatter fields does a SKILL.md file require?▼

Only name and description. The name uses letters, numbers, and hyphens in verb-first or gerund form like creating-skills, and the description states only when to use the skill.

Why do agents ignore my skill body and follow the description instead?▼

This happens when the description summarizes the workflow. Agents treat the summary as the instruction and skip the body. Strip the summary and keep only triggering conditions to fix it.