skills CLAUDE.md

CLAUDE.md

Claude-specific instructions for working on the Speakeasy Agent Skills repository.

Quick Reference

# Create a new skill
mkdir skills/{skill-name}
cp templates/SKILL.template.md skills/{skill-name}/SKILL.md

# Test a skill locally
cp -r skills/{skill-name} ~/.claude/skills/

# Reload Claude Code and test trigger phrases

Repository Structure

speakeasy-api/skills/
├── .claude-plugin/          # Claude Code plugin configuration
│   ├── plugin.json          # Plugin manifest (namespace: "speakeasy")
│   └── marketplace.json     # Marketplace metadata
├── skills/                  # Skill definitions
│   └── {skill-name}/
│       └── SKILL.md         # Skill instructions
├── templates/               # Skill templates
│   └── SKILL.template.md    # Template for new skills
├── AGENTS.md                # General agent guidance
├── CLAUDE.md                # This file (Claude-specific guidance)
├── README.md                # End-user documentation
└── LICENSE                  # Apache-2.0

Creating a New Skill

1. Directory Structure

mkdir skills/{skill-name}

Use kebab-case for directory names (e.g., manage-openapi-overlays).

2. SKILL.md Format

Every skill must have a SKILL.md file with YAML frontmatter. See templates/SKILL.template.md for a complete example.

Required structure:

---
name: skill-name
description: Use when [trigger condition]. Triggers on "X", "Y", or "Z".
license: Apache-2.0
---

Spec Reference: Skills follow the agentskills.io specification.

Required sections:

Section	Purpose
# skill-name	Title matching the directory name
## When to Use	Trigger scenarios and example phrases
## Inputs	Table of required/optional inputs
## Outputs	Table of what the skill produces
## Command	The speakeasy command to run
## Example	Working example with explanation