how-to-guide

Expected Format for Skill Files in knowledge-work-plugins: Complete Guide to SKILL.md Structure

May 25, 2026 anthropics/knowledge-work-plugins ↗

Skill files in the knowledge-work-plugins repository must be plain-text Markdown documents named exactly 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:

Framing – Sets conversational context and behavioral instructions
Trigger – Declares activation phrases or intents
Steps – Enumerates procedural stages and connector calls
Outputs – Defines JSON return structures
References – Links to auxiliary documentation
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, 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, 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 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, 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, 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 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 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
Location: Must reside within a skill-specific directory (e.g., 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:

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)


## 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": "<drafted reply>",
  "order_id": "12345",
  "approved": false
}

References

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


### 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


## 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.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how anthropics/knowledge-work-plugins works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →