Skill MD File Format Explained With Examples

Claude skills are plain Markdown files. The format combines YAML front matter with a Markdown body. The front matter stores metadata; the body is the system prompt.

The Basic Structure

A minimal skill file:

---
name: example-skill
description: A sample skill demonstrating the fundamental format
---

You are a specialized assistant for example tasks.

When invoked, you will:
1. Do the first thing
2. Do the second thing
3. Report back clearly

Front Matter Fields

name (required): The skill identifier. Used for manual invocation: /skill-name.

description (required): What the skill does. Used for auto-invocation matching. Write as a full sentence.

triggers (optional but recommended): Phrases that cause automatic invocation.

triggers:
  - phrase: create a component
  - phrase: build a new page

A Practical Example: The pdf Skill

The pdf skill extracts text, tables, and content from PDF files and can generate new PDFs. Here is its skill definition:

---
name: pdf
description: Extracts text and tables from PDF files and creates new PDFs
---

# PDF Skill

You are a PDF document specialist.

When to use this skill:
- Extracting text and tables from existing PDFs
- Creating new PDFs from Markdown or provided content
- Merging multiple PDF files

How to work:
1. Ask the user for the PDF file path or content
2. Use available tools to read the file or generate output
3. Present extracted content in clean, structured format

Invoke with: /pdf extract all tables from Q3-financial-report.pdf

A Practical Example: The tdd Skill

The tdd skill enforces test-driven development by writing failing tests before implementation. Here is its skill definition:

---
name: tdd
description: Test-driven development: writes failing tests first, then implementation
---

# TDD Skill

You are a test-driven development assistant.

Workflow:
1. Red phase: Write failing tests that describe the desired behavior
2. Green phase: Write the minimum code to make those tests pass
3. Refactor phase: Clean up implementation without changing tests

Before writing tests, check existing test files for:
- Testing framework (Jest, pytest, Vitest, etc.)
- Test file naming conventions
- Mock and fixture patterns already in use

Output: test file(s), then implementation file(s), then brief explanation.

Advanced Pattern: Reading Project Context Files

Skills can instruct Claude to read specific files at the start of every invocation:

---
name: frontend-design
description: Builds React components using the project's design system
---

At the start of every invocation, read:
- docs/design-tokens.md (color palette, spacing scale, typography)
- src/components/Button.tsx (as a component reference example)

Then build the requested component following the established patterns.

This is the correct way to inject project context into a skill: by instructing Claude to read files, not via special YAML configuration.

Optional Front Matter Fields

Beyond the required name and description, skill files support additional metadata:

tools (optional): Specify which Claude Code tools the skill should use. Without this field, Claude decides which tools to use based on the task.

tools: [Read, Write, Bash, Glob]

model (optional): Override the default model for this skill if you want a faster or more capable model for specific tasks.

temperature (optional): Control response randomness. Lower values (0.0–0.3) produce more consistent, predictable output; higher values (0.7–1.0) allow more creativity.

Writing Effective Skill Bodies

The body of a skill file is Claude’s system prompt. A few principles make skill bodies more effective:

Be specific about inputs. Tell Claude exactly what to ask the user for if it’s missing. Skills that silently guess at missing inputs produce inconsistent results.

Describe the output format. Whether you want a markdown table, a numbered list, or a code block, state it explicitly. Claude follows format instructions reliably when they’re in the system prompt.

Define scope boundaries. What should the skill NOT do? A code-review skill that also rewrites your code is often not what you want. Add explicit “do not” constraints.

Reference files by convention. If your skill depends on project-specific files (a design system, a style guide, an API spec), instruct Claude to read them at the start of every invocation rather than hardcoding their content.

Common Mistakes

Missing description: Skills without descriptions do not contribute to auto-invocation matching.

Generic trigger phrases: - phrase: help me with code fires on almost everything and causes the skill to activate at unintended moments.

Wrong directory: Files must be in .claude/ or ~/.claude/ (project-level or global). A subdirectory like ~/my-skills/ is not checked by Claude Code.

Tabs in YAML: The front matter uses YAML, which requires spaces for indentation — never tabs. Tabs cause silent parsing failures.

Built by theluckystrike - More at zovo.one