# Expected Format for Skill Files in knowledge-work-plugins: Complete Guide to SKILL.md Structure > Understand the SKILL.md format for knowledge-work-plugins. Learn the required sections like Framing Trigger Steps Outputs and References for effective skill file creation. - Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins) - Tags: how-to-guide - Published: 2026-05-25 --- **Skill files in the knowledge-work-plugins repository must be plain-text Markdown documents named exactly [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) that follow a rigid section order: Framing, Trigger, Steps, Outputs, References, and optional Gotchas.** Each skill file defines a self-contained workflow that Claude-powered plugins execute. The repository organizes these files under domain-specific directories (e.g., `small-business/skills/`, `data/skills/`), where the runtime automatically scans and registers them as executable capabilities. ## SKILL.md File Structure and Required Sections Every skill file follows a conventional structure that the plugin runtime parses to discover triggers, framing language, step-by-step actions, and output handling. The parser expects standard Markdown headings (`##`) and tolerates missing optional sections, but requires at least **Framing**, **Trigger**, and **Steps**. The canonical section order is: 1. **Framing** – Sets conversational context and behavioral instructions 2. **Trigger** – Declares activation phrases or intents 3. **Steps** – Enumerates procedural stages and connector calls 4. **Outputs** – Defines JSON return structures 5. **References** – Links to auxiliary documentation 6. **Gotchas** (optional) – Documents failure modes and edge cases ## Required Sections Explained ### Framing The **Framing** section establishes the persona and constraints for Claude when executing the skill. It typically begins with "You are the **[Skill-Name]** skill" and defines behavioral guardrails. According to the source code analysis, this text is cached by the runtime and prefixed to any user request matching the skill's trigger. For example, in [`small-business/skills/ticket-deflector/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/ticket-deflector/SKILL.md), the framing instructs Claude to "read a customer complaint, surface the relevant order details, and draft a courteous response" while prohibiting data invention. ### Trigger The **Trigger** section declares natural-language phrases or slash commands that activate the skill. These are typically formatted as bullet lists. The runtime extracts these phrases during startup and registers them as commands. In [`data/skills/sql-queries/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/sql-queries/SKILL.md), triggers include phrases like "show me the sales chart for last quarter" and "run query". ### Steps The **Steps** section enumerates numbered procedural stages describing what Claude should execute, which connectors to invoke, and any required approval gates. Each step must specify connector names in **bold** (e.g., `**QuickBooks MCP**`) so the runtime can resolve API calls. Destructive actions must include explicit approval steps phrased as `Confirm: "Do you want to …?"`. The [`small-business/skills/smb-router/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/smb-router/SKILL.md) demonstrates this pattern with ordered execution stages. ### Outputs The **Outputs** section defines the JSON schema returned to the caller. This typically includes a fenced code block containing the expected JSON structure with example values. In [`data/skills/sql-queries/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/sql-queries/SKILL.md), the outputs specify a structured response containing the generated SQL, parameters, and result set. ### References The **References** section provides relative links to supplementary Markdown files (e.g., [`gotchas.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/gotchas.md), schemas, or authentication guides). Use relative paths like `[reference/gotchas.md]` rather than absolute URLs to maintain repository portability. The [`marketing/skills/seo-audit/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/marketing/skills/seo-audit/SKILL.md) uses this section to link to auxiliary documentation. ### Gotchas (Optional) The **Gotchas** section documents common failure modes, edge cases, and mitigation strategies. While optional, its inclusion is recommended for complex integrations. For example, [`finance/skills/journal-entry/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/finance/skills/journal-entry/SKILL.md) lists edge cases such as missing connectors or token limit constraints. ## Key Conventions and Constraints ### File Naming and Location - **File name**: Must be exactly [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) - **Location**: Must reside within a skill-specific directory (e.g., [`partner-built/zoom-plugin/skills/zoom-mcp/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/skills/zoom-mcp/SKILL.md)) - **Section order**: Strictly `Framing → Trigger → Steps → Outputs → References → Gotchas` ### Markdown Syntax Rules - Use standard ATX headings (`##`) – do not use Setext-style underlines - Do not embed HTML tags or code fences within top-level sections, as these may break parsing - Use bullet lists (`- `) for triggers and references - Bold connector names using `**double asterisks**` ### Approval Gates Any destructive action (creating records, sending emails, modifying data) must be preceded by an explicit confirmation step. The conventional format is: ```markdown 4. **Confirm** – Ask the user "Send this response?" before any email is dispatched. ``` ## Complete SKILL.md Examples Below are three illustrative implementations demonstrating the required format for different domains. ### Customer Support Skill (Ticket-Deflector) ```markdown ## Framing You are the **Ticket-Deflector** skill. Your job is to read a customer complaint, surface the relevant order details, and draft a courteous response. Never invent data; always pull from the connected CRM or ask the user to paste the text. ## Trigger - "refund request" - "customer complaint" - "ticket #" ## Steps 1. **Detect ticket** – Look for a ticket identifier in the user message. 2. **Fetch order** – Call the **QuickBooks MCP** to retrieve order info. If the connector is unavailable, fall back to a CSV upload. 3. **Draft response** – Generate a templated reply that includes the order number and next steps. 4. **Confirm** – Ask the user "Send this response?" before any email is dispatched. ## Outputs ```json { "response_text": "", "order_id": "12345", "approved": false } ``` ## References - [reference/gotchas.md](reference/gotchas.md) - [reference/csv-schema.md](reference/csv-schema.md) ## Gotchas - **Missing connector** – If QuickBooks is not linked, the skill must gracefully prompt for a CSV file. - **Large complaint** – Truncate very long complaint texts to the first 2 KB to avoid token limits. ``` ### Data Analysis Skill (SQL-Queries) ```markdown ## Framing You are the **SQL-Queries** skill. Translate natural-language data requests into parameterized SQL statements against the configured data warehouse. ## Trigger - "show me the sales chart for last quarter" - "what's the average order value?" - "run query" ## Steps 1. **Parse intent** – Extract the target table, columns, and filters. 2. **Validate** – Ensure the user's request does not request restricted columns. 3. **Generate SQL** – Produce a safe parameterized query (e.g., using `?` placeholders). 4. **Execute** – Call the **Snowflake** connector; return the result set as a table. ## Outputs ```json { "sql": "SELECT AVG(amount) FROM orders WHERE date BETWEEN ? AND ?", "parameters": ["2023-01-01","2023-03-31"], "result": [...] } ``` ## References - [reference/sql-schema.md](reference/sql-schema.md) ``` ### Integration Skill (Zoom-MCP) ```markdown ## Framing You are the **Zoom-MCP** skill. Provide information about a Zoom meeting (participants, recordings, live transcript) using the Zoom MCP API. ## Trigger - "show me the Zoom meeting" - "who joined the last call?" - "Zoom transcript" ## Steps 1. **Identify meeting** – Accept a meeting ID or URL from the user. 2. **Call API** – Use the **zoom-mcp** connector to fetch meeting details. 3. **Present summary** – List participants, duration, and any available recordings. 4. **Optional transcript** – If the user asks for the transcript, retrieve and display it. ## Outputs ```json { "meeting_id": "123456789", "participants": ["Alice","Bob"], "duration_minutes": 45, "recording_url": "https://zoom.us/rec/…" } ``` ## References - [reference/error-codes.md](reference/error-codes.md) - [reference/authentication-and-identifiers.md](reference/authentication-and-identifiers.md) ``` ## How the Runtime Parses SKILL.md Files The plugin runtime scans every [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) under the repository tree to build the skill registry. During initialization: 1. **Discovery**: The parser recursively searches for files named exactly [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) 2. **Trigger extraction**: It extracts phrases from the **Trigger** section and registers them as slash commands or natural-language triggers for Claude 3. **Framing cache**: The **Framing** text is cached and prefixed to any matching user request, ensuring Claude operates with the correct domain knowledge and constraints 4. **Connector resolution**: Bolded connector names in **Steps** are mapped to available MCP (Model Context Protocol) connectors This mechanism enables seamless integration across diverse domains including SMB workflows ([`small-business/skills/ticket-deflector/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/ticket-deflector/SKILL.md)), data operations ([`data/skills/sql-queries/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/sql-queries/SKILL.md)), and partner-built integrations ([`partner-built/zoom-plugin/skills/zoom-mcp/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/partner-built/zoom-plugin/skills/zoom-mcp/SKILL.md)). ## Summary - **Skill files** must be named exactly [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) and use standard Markdown syntax with ATX headings - **Required sections** follow a strict order: Framing, Trigger, Steps, Outputs, References, and optional Gotchas - **Triggers** are registered automatically by the runtime to activate skills via natural language - **Connectors** must be bolded in Steps to enable proper API resolution (e.g., `**QuickBooks MCP**`) - **Destructive actions** require explicit confirmation steps before execution - **References** should use relative paths to maintain repository portability ## Frequently Asked Questions ### What happens if I include HTML tags in my SKILL.md file? The parser may break or skip sections containing HTML tags. According to the knowledge-work-plugins conventions, you should use standard Markdown only—avoid HTML, and avoid embedding code fences within the top-level sections like Framing or Trigger. ### Can I reorder the sections or omit the References section? You can omit optional sections like **Gotchas** or **References**, but you must maintain the canonical order for required sections (Framing → Trigger → Steps → Outputs). The parser tolerates missing optional sections but expects the remaining sections to appear in the prescribed sequence. ### How do I reference external APIs or connectors in my skill? Reference connector names using **double asterisks** within the Steps section. For example, write `**QuickBooks MCP**` or `**Snowflake**` so the runtime can resolve the appropriate API. Ensure you include approval gates before any destructive connector calls. ### Where should I place my SKILL.md file in the repository? Place your [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file within a directory representing the specific skill, typically under a domain folder. Examples from the source code include [`small-business/skills/ticket-deflector/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/ticket-deflector/SKILL.md) and [`data/skills/sql-queries/SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/data/skills/sql-queries/SKILL.md). The runtime scans the entire tree recursively, but organizing by domain improves maintainability.