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

> Understand the core components of a knowledge-work-plugin skill, including SKILL.md structure, schema, and best practices. Learn to build effective plugins with our expert guide.

- Repository: [Anthropic/knowledge-work-plugins](https://github.com/anthropics/knowledge-work-plugins)
- Tags: best-practices
- Published: 2026-05-25

---

**A knowledge-work-plugin skill requires a [`SKILL.md`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/SKILL.md) file begins with YAML front-matter that declares the skill's identity and trigger conditions. According to the [component schema specification](https://github.com/anthropics/knowledge-work-plugins/blob/main/cowork-plugin-management/skills/create-cowork-plugin/references/component-schemas.md#skills), 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

```yaml
---
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](https://github.com/anthropics/knowledge-work-plugins/blob/main/small-business/skills/ticket-deflector/SKILL.md), 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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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:

```text
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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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`](https://github.com/anthropics/knowledge-work-plugins/blob/main/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.