skills: Instructions file for Codex

AGENTS.md

This file provides guidance for AI coding agents working on the Speakeasy Agent Skills repository. It covers how to create, maintain, and improve skills for the Speakeasy CLI.

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                # This file (contributor guidance)
├── CLAUDE.md                # Claude-specific contributor 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]. Include phrases like "X", "Y", or "Z".
---

Required sections:

Section	Purpose
# skill-name	Title matching the directory name
## When to Use	Trigger scenarios and example phrases
## Command	The speakeasy command to run
## Example	Working example with explanation

Recommended sections:

Section	Purpose
## Prerequisites	Required setup, env vars, dependencies
## Decision Framework	Table mapping situations to actions
## What NOT to Do	Anti-patterns the AI should avoid
## Related Skills	Links to related skills

3. Naming Conventions

• Directory: kebab-case (e.g., start-new-sdk-project)
• SKILL.md: Always uppercase, exact filename
• Frontmatter name: Must match directory name exactly