common-skills: Skill for Claude Code

update-skill

This guide provides instructions for creating or updating skills in this repository. It covers the required structure, frontmatter, and best practices for skills.

Quick Start

Every skill is a directory containing a SKILL.md file with YAML frontmatter and markdown body:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

# PDF Processing

## When to use this skill
Use this skill when the user needs to work with PDF files...

## How to extract text
1. Use pdfplumber for text extraction...

## How to fill forms
...

Requirements

Frontmatter (Required)

Every SKILL.md must start with YAML frontmatter containing:

• name: Kebab-case identifier (lowercase letters, numbers, hyphens only)
  • Example: add-feature-flag, pdf-processing, update-skill
• description: Specific description of what the skill does and when to use it
  • Must be non-empty
  • Should include key terms for skill discovery
  • Begin with an action verb to clearly state what the skill accomplishes (e.g., "Adds feature flags..." instead of "Helps with features..."), and immediately follow with a specific use case or context (e.g., "Use when working with feature flags")
  • Write in third person (e.g., "Adds feature flags..." not "I can help you add...")

Writing Effective Descriptions

The description field is critical for skill discovery. Include both what the skill does and when to use it. Some good examples:

• git-commit: "Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes."
• pdf-processing: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."

Avoid vague descriptions like "Helps with code" or "Does development tasks". For more context, see "Description Best Practices" in references/best-practices.md.