skills.rest
jeremylightsmith
jeremylightsmithCOMMUNITY
Explore all skills by this author →
Website𝕏@lightsmithGitHub

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
One-click install
npx skills add https://github.com/jeremylightsmith/relay-config --skill writing-skills-jeremylightsmith
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Software Engineering Skills→
krafton-aikrafton-ai
929

skill-creator

Creates and refines reusable SKILL.md skill packages for KiraClaw agents.

Official
Basic
gabrielfruetgabrielfruet
3

skill-writter

Create agent skills with valid YAML frontmatter and trigger descriptions.

Community
Intermediate
V4-CompanyV4-Company
2

marsai:testing-skills-with-subagents

Test MarsAI skills through RED-GREEN-REFACTOR cycles with subagents.

Official
Advanced
knckknckknckknck

go-style-guide

Standardize Go code quality and style across projects.

Community
Intermediate