SKILL.md File Format and Required Frontmatter Structure

SKILL.md files are YAML-fronted Markdown documents requiring name and description fields to register skills for Instagit workshop agents.

The anthropics/cwc-workshops repository utilizes SKILL.md files to define agent capabilities within its workshop environments. These files combine structured metadata with free-form documentation, enabling the system to catalog skills while providing AI agents with detailed implementation guidance.

Required Frontmatter Fields

Every SKILL.md file must begin with a YAML frontmatter block enclosed by triple dashes (---). The system strictly enforces two mandatory fields within this block to successfully register the skill.

The name Field

The name field defines a unique string identifier that the Instagit system uses internally to reference the skill. This value must be distinct across the workshop environment to prevent registration conflicts and enable precise skill invocation.

The description Field

The description field provides a concise, human-readable summary explaining the skill's functionality. This metadata allows both developers and AI agents to quickly understand capabilities without parsing implementation details or extensive documentation.

File Structure and Syntax

The SKILL.md format follows standard Markdown conventions with a mandatory YAML header. The structure requires:

• Opening and closing delimiters (---) on their own lines
• Mandatory name and description key-value pairs
• Standard YAML syntax compliance
• Unrestricted Markdown content following the closing delimiter

After the frontmatter block, authors may include any valid Markdown content such as usage instructions, API references, or code snippets.

---
name: data-processor
description: Processes incoming JSON payloads and validates schema compliance.
---

## Usage Example

Call the processor with a JSON object:

```python
def process(data):
    return validate_schema(data)

## Real-World Examples from the Repository

Examining existing skills in `anthropics/cwc-workshops` demonstrates the frontmatter requirements in production contexts.

In [`research-desk/skills/edgartools/SKILL.md`](https://github.com/anthropics/cwc-workshops/blob/main/research-desk/skills/edgartools/SKILL.md), the frontmatter specifies `name: edgartools-sec-data` alongside a detailed description explaining the skill's purpose for retrieving SEC filing data.

In [`agent-battle/skills/mining/SKILL.md`](https://github.com/anthropics/cwc-workshops/blob/main/agent-battle/skills/mining/SKILL.md), the configuration uses `name: mining` with a concise description appropriate for the agent battle context.

Both implementations confirm that while the content length following the frontmatter varies significantly, the `name` and `description` fields remain constant requirements at the top of every [`SKILL.md`](https://github.com/anthropics/cwc-workshops/blob/main/SKILL.md) file.

## Optional Metadata Fields

While the system strictly requires `name` and `description`, the YAML frontmatter accepts additional optional keys following standard YAML syntax. Developers may include:

- **tags**: Categorical labels for skill organization and filtering
- **author**: Attribution metadata for maintenance tracking

These optional fields do not affect skill registration but provide useful context for documentation workflows and repository management.

## Summary

- **SKILL.md files** are Markdown documents with YAML frontmatter used by Instagit workshop agents in `anthropics/cwc-workshops`
- **Required frontmatter** must include `name` (unique identifier) and `description` (human-readable summary) wrapped in triple-dash delimiters
- **File locations** follow patterns like [`research-desk/skills/edgartools/SKILL.md`](https://github.com/anthropics/cwc-workshops/blob/main/research-desk/skills/edgartools/SKILL.md) and [`agent-battle/skills/mining/SKILL.md`](https://github.com/anthropics/cwc-workshops/blob/main/agent-battle/skills/mining/SKILL.md)
- **Content flexibility** allows any Markdown after the frontmatter for code examples and usage documentation
- **Optional fields** such as `tags` or `author` may be added but are not required for registration

## Frequently Asked Questions

### What happens if I omit the `name` or `description` fields in a SKILL.md file?

The Instagit workshop agent system requires both fields to register and list the skill properly. Omitting either field will prevent the skill from being recognized by the agent framework, though the Markdown content itself remains syntactically valid.

### Can I use markdown formatting inside the `description` field?

The `description` field accepts plain text strings. While YAML syntax technically allows certain markdown-like characters, the field is intended for concise human-readable summaries. Complex formatting should be reserved for the free-form Markdown section following the frontmatter block.

### Are there restrictions on the `name` field format?

The `name` field functions as a unique internal identifier. According to the repository conventions demonstrated in files like [`agent-battle/skills/mining/SKILL.md`](https://github.com/anthropics/cwc-workshops/blob/main/agent-battle/skills/mining/SKILL.md) and [`research-desk/skills/edgartools/SKILL.md`](https://github.com/anthropics/cwc-workshops/blob/main/research-desk/skills/edgartools/SKILL.md), using lowercase alphanumeric characters with hyphens (e.g., `edgartools-sec-data`) ensures compatibility with the registration system.

### Where should I place my SKILL.md file within the project structure?

Place [`SKILL.md`](https://github.com/anthropics/cwc-workshops/blob/main/SKILL.md) files within skill-specific subdirectories. The repository places them at paths like [`research-desk/skills/edgartools/SKILL.md`](https://github.com/anthropics/cwc-workshops/blob/main/research-desk/skills/edgartools/SKILL.md), indicating that each skill should reside in its own folder with the documentation file at the root of that folder.

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