Core Components of a Knowledge-Work-Plugin Skill: Structure, Schema, and Best Practices

A knowledge-work-plugin skill requires a SKILL.md file with mandatory YAML front-matter (name and description) and an imperative body section, residing in a dedicated directory under skills/ with optional support folders for references, examples, and scripts.

The anthropics/knowledge-work-plugins repository defines a modular architecture where encapsulated capabilities are distributed as discrete, self-contained units. Each knowledge-work-plugin skill lives in its own directory and follows a progressive enhancement model—core behavior is always available via the primary definition file, while richer documentation and automation reside in optional sibling folders. This structure ensures portability across different plugin runtimes while maintaining strict schema compliance.

Required Core Components

Every skill must implement two foundational elements: a dedicated directory and a primary definition file containing both metadata and execution logic.

The Skill Directory

Each skill occupies a unique folder under the skills/ root path following the convention skills/<skill-name>/. The directory name must match the name field defined in the skill's front-matter, using lowercase, hyphenated formatting (e.g., skills/ticket-deflector/). This directory serves as the namespace for all related assets.

SKILL.md Front-Matter Schema

The SKILL.md file begins with YAML front-matter that declares the skill's identity and trigger conditions. According to the component schema specification, three fields are recognized:

• name – A lowercase, hyphenated identifier matching the directory name
• description – A concise third-person sentence listing trigger phrases (e.g., "draft a response", "design an API")
• metadata – An optional map for key-value pairs such as version, author, or tags

---
name: api-design
description: >
  This skill should be used when the user asks to "design an API",
  "create API endpoints", or "review API structure".
metadata:
  version: "0.1.0"
---

The Body Content

Following the front-matter, the body contains the core knowledge injected into the model context when the skill fires. As implemented in the Ticket-Deflector skill, this section uses imperative, third-person prose describing the workflow, decision trees, and output formats. Content should remain between 1,500–2,000 words (maximum ~3,000) to optimize context window utilization while preserving directive clarity.

Optional Support Components

The architecture supports progressive enhancement through three optional directory structures that extend functionality without bloating the core definition.

References Documentation

The references/ folder contains deep-dive Markdown files covering advanced patterns, edge cases, or regulatory constraints. The runtime loads these on-demand when the skill requires specialized knowledge. For example, the Ticket-Deflector skill includes references/gotchas.md to handle specific refund policy exceptions.

Executable Examples

The examples/ directory stores ready-to-run snippets demonstrating input/output formats or API interaction patterns. These files illustrate concrete use cases, such as examples/respond-refund-request.md, providing the model with few-shot templates for complex tasks.

Automation Scripts

The scripts/ folder houses helper executables (Bash, Python, etc.) that the skill invokes via the runtime's tool-call mechanism. As shown in the component schema, a skill can execute scripts/validate.sh to perform external validation before proceeding with logic execution.

Directory Structure and File Layout

A complete skill directory follows this hierarchical pattern:

skills/ticket-deflector/
├── SKILL.md                    # Core definition (required)

├── references/
│   ├── gotchas.md              # Advanced guidance

│   └── examples/
│       └── respond-refund-request.md
├── examples/
│   └── sample-email.txt        # Sample inputs

└── scripts/
    └── validate.sh             # Helper executable

The SKILL.md file must exist at the root; all other directories are optional but follow strict naming conventions when present.

Architecture and Runtime Behavior

When Claude receives a user request, the knowledge-work-plugin runtime executes a four-stage loading process:

1. Trigger Matching – The system compares user input against the description field across all available skills to identify candidates
2. Metadata Loading – The runtime parses the YAML front-matter to confirm the skill identity and extract configuration
3. Knowledge Injection – The body content is injected into the prompt context, optionally augmented by specific references/ or examples/ files referenced in the conversation
4. Script Execution – If the skill body contains script invocation syntax (e.g., !`${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`), the runtime executes the command and returns stdout to the model

This progressive loading ensures skills remain functional even when auxiliary resources are unavailable, while allowing for dynamic extension via the references/ and scripts/ hooks.

Summary

• A knowledge-work-plugin skill is fundamentally defined by a SKILL.md file containing YAML front-matter (name, description, optional metadata) and an imperative body section
• Skills reside in dedicated directories under skills/<hyphenated-name>/ as specified in component-schemas.md
• Optional directories (references/, examples/, scripts/) provide progressive enhancement for complex workflows
• The runtime matches trigger phrases against the description field, then loads the body content with optional on-demand resources
• Script execution uses the ! syntax to invoke helpers from the scripts/ folder under the plugin's allowed-tools constraints

Frequently Asked Questions

What is the minimum file structure needed to create a knowledge-work-plugin skill?

The absolute minimum requires a single file: skills/<skill-name>/SKILL.md containing valid YAML front-matter with name and description fields, plus a body section describing the workflow. No additional folders or configuration files are necessary for the skill to function, though production skills typically include references/ and examples/ directories for robustness.

How does the plugin runtime determine when to activate a specific skill?

The runtime evaluates the description field in each skill's front-matter as a trigger matcher. When user input contains phrases defined in that description—such as "design an API" or "draft a response"—the corresponding skill's body content is loaded into the context window. This declarative matching system allows multiple skills to coexist without hard-coded routing logic.

What conventions should be followed when writing the body content of SKILL.md?

Body content should use imperative, third-person instructions directed at the AI (e.g., "Parse the requirements," "Generate the output"). Keep the text between 1,500–2,000 words to balance comprehensiveness with context window constraints. Avoid first-person narration; the body functions as a system prompt that guides the model's behavior when the skill fires.

Can skills execute external system commands, and what are the security implications?

Yes, skills can invoke scripts from their local scripts/ directory using the ! prefix syntax (e.g., ![`./scripts/validate.sh`](https://github.com/anthropics/knowledge-work-plugins/blob/main/./scripts/validate.sh)). However, execution is constrained by the plugin runtime's allowed-tools configuration and hooks.json definitions. Scripts run in a sandboxed environment with access limited to the skill's own directory and explicitly permitted external resources, preventing unauthorized system access.

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