writing-skills

Use when creating or updating SKILL.md documentation - Explains how and why to create a skill.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 11, 2025

When & Why to Use This Skill

This Claude skill provides a standardized framework and comprehensive guidelines for creating and maintaining 'Skills'—modular context units designed to enhance coding agent performance. It ensures that documentation is concise, properly structured, and optimized for LLM consumption, preventing context bloat while providing the agent with essential task-specific knowledge.

Use Cases

  • Standardizing Skill Creation: Establishing a consistent directory structure and metadata format for all new agent capabilities to ensure seamless integration.
  • Context Window Optimization: Implementing modular skill sets that allow agents to access specific domain knowledge only when needed, reducing token usage and improving response accuracy.
  • Documentation Best Practices: Guiding developers on writing effective SKILL.md files with precise front matter and scannable instructions for better agent interpretation.
  • Automated Workflow Integration: Ensuring skill directories are correctly formatted for automated tools and GitHub Actions that manage agent manifests and capability lists.
namewriting-skills
description"Use when creating or updating SKILL.md documentation - Explains how and why to create a skill."

Skills are used to for context that may be useful to a coding agent, without bloating LLM context at times theyre not useful.

Skills are only worthwhile if the coding agent fails a task without the skill.

Skills live in /.skills, with each skill having its own directory.

SKILL.md

Front matter

  • Match the name to the directory name exactly.
  • Write the description as "Use when - " in under 30 words and third person.
  • Quote the description if it includes punctuation that could break YAML.

Markdown body

  • Write concise instructions for the skill topic.
  • Keep headings and bullet lists structured so readers can scan quickly.

Aditional files

Other files, like scripts or data, may live in the directory and be referenced by the skill.

AGENTS.md

A GitHub Action automatically regenerates the skills list in AGENTS.md.