> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/anthropics/skills/llms.txt > Use this file to discover all available pages before exploring further. # SKILL.md Format and Structure > Complete reference for the SKILL.md file format, including YAML frontmatter, markdown body, and best practices for writing effective skill instructions. The `SKILL.md` file is the core of every skill. It contains YAML frontmatter with metadata and a markdown body with instructions that the AI agent will follow when the skill is active. ## File Structure A SKILL.md file has two parts: 1. **YAML Frontmatter** - Metadata enclosed in `---` delimiters 2. **Markdown Body** - Instructions, examples, and guidelines ```markdown theme={null} --- name: my-skill-name description: A clear description of what this skill does and when to use it compatibility: [optional] Required tools or dependencies --- # Skill Instructions [Markdown content with instructions, examples, and guidelines] ``` ## YAML Frontmatter ### Required Fields Unique identifier for the skill. Use lowercase letters, numbers, and hyphens. No spaces. ```yaml theme={null} name: mcp-builder ``` Complete description of what the skill does and when to use it. This is the **primary triggering mechanism** - include both capabilities and specific contexts for when to use the skill. The description should be "pushy" to combat Claude's tendency to under-trigger skills. Include: * What the skill does * When to use it (specific contexts, keywords, scenarios) * What it enables ```yaml theme={null} description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). ``` ### Optional Fields Required tools, dependencies, or platform requirements. Rarely needed. ```yaml theme={null} compatibility: Requires WebFetch tool for loading API documentation ``` License information or reference to a LICENSE.txt file in the skill folder. ```yaml theme={null} license: Apache 2.0 # or license: Complete terms in LICENSE.txt ``` ## Markdown Body The markdown body contains the instructions the AI agent will follow. This is where you teach the agent how to accomplish the skill's task. ### Structure Guidelines The SKILL.md body should ideally be under 500 lines. If approaching this limit: * Move detailed documentation to reference files * Add clear pointers about when to read each reference * Use progressive disclosure to load details on demand Example: ```markdown theme={null} ## Implementation For language-specific implementation details: - [⚡ TypeScript Guide](./reference/node_mcp_server.md) - [🐍 Python Guide](./reference/python_mcp_server.md) ``` Modern AI agents benefit from understanding **why** things are important, not just what to do. **Good:** ```markdown theme={null} Clear, descriptive tool names help agents find the right tools quickly. Use consistent prefixes (e.g., `github_create_issue`, `github_list_repos`) and action-oriented naming. ``` **Less effective:** ```markdown theme={null} ALWAYS use descriptive tool names. NEVER use abbreviations. ``` Prefer imperative instructions for clarity: ```markdown theme={null} ## Report Structure ALWAYS use this exact template: # [Title] ## Executive Summary ## Key Findings ## Recommendations ``` Examples help agents understand expected input/output formats: ```markdown theme={null} ## Commit Message Format **Example 1:** Input: Added user authentication with JWT tokens Output: feat(auth): implement JWT-based authentication **Example 2:** Input: Fixed crash when user logs out Output: fix(auth): prevent crash on logout ``` When referencing bundled resources, be explicit about when and how to use them: ````markdown theme={null} ## API Documentation For framework-specific implementation: - **TypeScript**: Read [reference/node_mcp_server.md](./reference/node_mcp_server.md) - **Python**: Read [reference/python_mcp_server.md](./reference/python_mcp_server.md) ## Validation Use the provided validation script: ```bash python scripts/validate_output.py ```` ### Common Patterns #### Defining Output Formats ````markdown theme={null} ## Output Format Generate a JSON file with this structure: ```json { "name": "string", "version": "string", "dependencies": [] } ```` Ensure all fields are present and properly formatted. ```` #### Multi-Step Workflows ```markdown ## Process ### Phase 1: Research and Planning 1. Review the API documentation 2. Identify key endpoints to implement 3. Plan authentication approach ### Phase 2: Implementation 1. Set up project structure 2. Implement core infrastructure 3. Implement individual tools ### Phase 3: Testing 1. Create test cases 2. Run validation scripts 3. Review results ```` #### Conditional Instructions ```markdown theme={null} ## Platform-Specific Instructions **For TypeScript:** - Use Zod for input validation - Use the MCP TypeScript SDK - Follow the TypeScript guide in references/ **For Python:** - Use Pydantic for input validation - Use the MCP Python SDK - Follow the Python guide in references/ ``` #### Error Handling ```markdown theme={null} ## Error Handling When errors occur: 1. Read the error message carefully 2. Check if the issue is in the bundled documentation 3. Provide actionable error messages to the user 4. Suggest specific next steps Common errors: - **Authentication failed**: Check API credentials in environment variables - **Rate limit exceeded**: Wait 60 seconds and retry - **Invalid input**: Validate against the schema in references/schema.md ``` ## Writing Style ### Theory of Mind Write instructions with an understanding of how AI agents think and work: * Agents benefit from context and reasoning * Agents can generalize from principles * Agents work better with "why" than rigid "always/never" rules * Agents can compose solutions from flexible guidelines ### Generality vs. Specificity Balance general principles with specific examples: ```markdown theme={null} ## Tool Naming Use clear, action-oriented names that describe what the tool does. Consistent prefixes help with discoverability. **Examples:** - `github_create_issue` - Creates a new GitHub issue - `github_list_repos` - Lists repositories - `github_update_pr` - Updates a pull request Notice the pattern: `service_action_resource` ``` ### Avoiding Over-Specification If you find yourself writing ALWAYS or NEVER in all caps frequently, consider whether you can explain the reasoning instead. Rigid structures work less well than flexible guidelines grounded in understanding. Instead of: ```markdown theme={null} You MUST ALWAYS create a validation script. You MUST NEVER skip error handling. ALWAYS use the exact template provided. ``` Try: ```markdown theme={null} Validation scripts catch errors early and can be reused across runs. Write a validation script for any objectively verifiable requirements. Error handling helps agents recover gracefully and provides clear feedback. Include specific error messages and suggested next steps. ``` ## Complete Example Here's a complete SKILL.md example: ```markdown theme={null} --- name: commit-message-formatter description: Format git commit messages following conventional commits specification. Use when creating commits, formatting commit messages, or standardizing repository commit history. --- # Commit Message Formatter Format git commit messages following the Conventional Commits specification. ## Format Use this structure: ``` \(\): \ \[optional body] \[optional footer] ``` ## Types - **feat**: New feature - **fix**: Bug fix - **docs**: Documentation only - **style**: Formatting, missing semicolons, etc. - **refactor**: Code change that neither fixes a bug nor adds a feature - **test**: Adding missing tests - **chore**: Changes to build process or auxiliary tools ## Examples **Example 1:** Input: Added user authentication with JWT tokens Output: `feat(auth): implement JWT-based authentication` **Example 2:** Input: Fixed crash when user logs out Output: `fix(auth): prevent crash on logout` **Example 3:** Input: Updated README with API documentation Output: `docs(api): add endpoint documentation to README` ## Guidelines - Keep description under 72 characters - Use present tense ("add" not "added") - Don't capitalize first letter of description - No period at the end of description - Scope is optional but recommended ``` ## Next Steps Detailed schema reference for YAML frontmatter How the progressive disclosure system works This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.