Markdown Format for Skill Definitions in Claude Knowledge‑Work Plugins

Skill definitions in the Knowledge‑Work Plugins repository follow a strict Markdown schema that combines YAML front‑matter metadata with human‑readable workflow instructions, requiring no executable code.

The anthropics/knowledge-work-plugins repository enables custom automations through declarative skill files placed in plugin directories. Understanding the markdown format for skill definitions allows developers to create capabilities that Claude automatically surfaces and executes when users invoke specific workflows.

Anatomy of a Skill Definition File

Each skill is defined by a single Markdown (.md) file located under a plugin’s skills/ directory. The Claude engine parses these files to register available capabilities and extract execution instructions.

Required YAML Front‑Matter

Every skill file must begin with YAML front‑matter wrapped in triple dashes. This metadata block declares the machine‑readable identity and presentation details:

---
name: write-spec
description: Write a feature spec or PRD from a problem statement or feature idea.
argument-hint: "<feature or problem statement>"
---

The supported fields include:

• name – Machine‑readable identifier used for slash commands (e.g., ticket-deflector).
• description – One‑sentence purpose shown in UI skill lists.
• argument-hint (optional) – Placeholder text displayed when the skill expects user input.
• compatibility (optional) – Human‑readable list of required and optional connectors (e.g., "Requires PayPal, HubSpot, Mail. Optional: Intercom, Square.").

Document Structure and Content

Following the front‑matter, the remainder of the file uses standard Markdown syntax to guide Claude’s behavior:

1. Top‑Level Heading – A human‑readable title (e.g., # Write Spec) that mirrors the name field.

2. Usage Sections – Fenced code blocks demonstrating invocation patterns such as /write-spec $ARGUMENTS.

3. Workflow Description – Numbered steps detailing how to fetch data, enforce approval gates, and format outputs.

4. Reference Links – Relative paths to ancillary documentation like reference/gotchas.md or reference/examples/*.md.

The file contains no executable code; the engine treats the content as plain text instructions that Claude follows when matching user requests against the skill description.

Real‑World Examples from the Repository

Examining production skills in anthropics/knowledge-work-plugins demonstrates how the markdown format handles complex integrations and conditional logic.

Ticket‑Deflector Skill (Small Business)

The file small-business/skills/ticket-deflector/SKILL.md illustrates the compatibility field for connector dependencies:

---
name: ticket-deflector
description: >
  Reads a forwarded customer email or ticket, pulls order/refund status from
  PayPal and account history from HubSpot, drafts a tone‑matched reply in the
  owner’s writing voice, and can issue a PayPal refund with explicit owner
  approval. Use when the user says "draft a response," "answer this customer,"
  "where's my order," or "I want a refund."
compatibility: "Requires PayPal, HubSpot, Mail. Optional: Intercom, Square."
---

This implementation includes a detailed workflow section that instructs Claude to validate email content, query the PayPal API for transaction status, and pause for explicit owner approval before issuing refunds.

Write‑Spec Skill (Product Management)

Located at product-management/skills/write-spec/SKILL.md, this skill demonstrates the optional argument-hint field for parameterized natural language commands:

---
name: write-spec
description: Write a feature spec or PRD from a problem statement or feature idea. Use when turning a vague idea or user request into a structured document.
argument-hint: "<feature or problem statement>"
---

The document structure includes a "Quick start" code block showing example user phrasing and a numbered workflow that guides Claude through extracting requirements, researching existing features, and formatting the final specification document.

Summary

• Skill definitions are pure Markdown files stored in skills/ subdirectories, containing declarative metadata and instructional text.
• YAML front‑matter (delimited by ---) requires name and description fields, with optional argument-hint and compatibility declarations.
• The top‑level markdown heading provides the human‑readable title, followed by usage examples and step‑by‑step workflow instructions.
• Production examples in small-business/skills/ticket-deflector/SKILL.md and product-management/skills/write-spec/SKILL.md demonstrate connector integration patterns and complex conditional workflows.

Frequently Asked Questions

What fields are required in the YAML front‑matter?

The name and description fields are mandatory. The name serves as the machine‑readable identifier used in slash commands, while description provides the human‑readable summary displayed in skill selection interfaces. Fields like argument-hint and compatibility are optional but recommended for skills that accept parameters or require external connectors.

Can skill definitions contain executable code?

No. Skill files contain only Markdown content and YAML front‑matter metadata. The Claude engine parses the metadata to register the skill and treats the body as instructional text. Actual execution occurs through configured connectors referenced in the workflow steps, not through code embedded in the skill definition itself.

Where must skill files be located within the repository?

Each skill requires its own subdirectory under a plugin’s skills/ folder, with the main definition file named exactly SKILL.md. For example, product-management/skills/write-spec/SKILL.md follows the required path convention that enables automatic discovery and registration by the Claude engine.

How does the argument‑hint field influence skill invocation?

The argument‑hint field displays placeholder text in the user interface when the skill expects specific input parameters. This guides users to provide appropriate arguments when invoking the skill via natural language or slash commands, ensuring Claude receives the necessary context to execute the workflow accurately.

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