agent-spec

Design and validate Claude Code agent specifications with YAML frontmatter schemas.

Updated Jan 8, 2026

Search Tags:#documentation #subagents #plugin #yaml #claude-code #frontmatter #agent-spec

Ready to run

npx skills add https://github.com/biwakonbu/cc-plugins --skill agent-spec

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: agent-spec
Source: https://github.com/biwakonbu/cc-plugins/tree/main/plugins/plugin-generator/skills/agent-spec
Command: npx skills add https://github.com/biwakonbu/cc-plugins --skill agent-spec

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill provides formal knowledge and tooling expectations for designing and validating Claude Code agents and subagents, ensuring consistent frontmatter schemas and correct integration with tools, models, and skills fields.

Core Features & Use Cases

Documentation and validation of agent file structure according to the official frontmatter requirements.
Guidance on placing agent data under agents/{agent-name}.md and optionally categorizing with subdirectories.
Use when creating, updating, or maintaining agents, understanding agent structure, or implementing subagents.

Quick Start

Create an agents/{agent-name}.md file with a frontmatter containing name and description. Optional fields such as tools, model, permissionMode, and skills can be added as needed.

Frequently Asked Questions about agent-spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I structure YAML frontmatter for Claude Code subagents?▼

Claude Code subagent frontmatter requires a YAML block with `name` and `description` fields. Optional fields include `tools`, `model`, `permissionMode`, and `skills` to define allowed tools, model selection, and integration with other plugins.

What is the correct file location for Claude Code agent specifications?▼

Agent specifications should be placed in `agents/{agent-name}.md`. You can optionally categorize agents further by organizing them within subdirectories under the `agents` folder for better structural management.

How do I validate an agent file structure for Claude Code plugins?▼

Validating an agent file structure involves checking the YAML frontmatter for required `name` and `description` fields and ensuring optional fields like `tools` and `model` adhere to the official agent structure guidelines.

Can I integrate skills fields into Claude Code agent frontmatter?▼

Yes, you can integrate `skills` into Claude Code agent frontmatter. It is an optional field that allows the agent to work with other skills, alongside other optional fields like `tools` and `model`.

What's the best way to update existing Claude Code agent specifications?▼

To update Claude Code agent specifications, modify the YAML frontmatter in your `agents/{agent-name}.md` file. Ensure changes to fields like `tools`, `model`, or `skills` comply with the official agent structure guidelines.

Why does my Claude Code agent configuration not recognize the tools field?▼

The `tools` field might not be recognized if the YAML frontmatter is malformed or the agent structure guidelines are not followed. Ensure the frontmatter syntax is correct and the `tools` field is properly configured.