subagent-best-practices

Name: subagent-best-practices
Availability: InStock
Author: sunagaku

Enforce YAML frontmatter and 3-Phase workflows for SubAgent definitions.

35|Updated Feb 15, 2026

Search Tags:#agents #subagent #best-practices #yaml-frontmatter #context-passing #phase-design

Ready to run

npx skills add https://github.com/sean-sunagaku/claude-code-plugin --skill subagent-best-practices

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: subagent-best-practices
Source: https://github.com/sean-sunagaku/claude-code-plugin/tree/main/subagent-best-practices/skills/subagent-best-practices
Command: npx skills add https://github.com/sean-sunagaku/claude-code-plugin --skill subagent-best-practices

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Claude Code の SubAgent（agents/*.md）を正しく定義するためのベストプラクティスガイド。 YAML frontmatter、ツール選択、3-Phase 構造、コンテキスト受け渡し、アンチパターンを網羅。

Core Features & Use Cases

YAML frontmatter の厳格な記述ルールとテンプレートの活用
SubAgent 定義の 3-Phase 構造の標準化とエッジケース対策
コンテキスト受け渡しの推奨パターンと MCP に対する回避策
references のテンプレートとチェックリストの活用

Quick Start

Follow the frontmatter standards and the provided templates in references to start writing robust agents/*.md definitions.

Frequently Asked Questions about subagent-best-practices

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

FAQPage Schema

How do I define a SubAgent in Claude Code using YAML frontmatter?▼

To define a SubAgent, you create an agents/*.md file with strict YAML frontmatter conventions, specifying tools, name, and description. This skill provides templates and rules to ensure your SubAgent definitions are robust, safe, and auditable.

What is the 3-Phase workflow structure for SubAgent definitions?▼

The 3-Phase workflow structure is a standardized design pattern for SubAgent definitions that separates tasks into distinct phases. This skill guides you through structuring prompts, handling edge cases, and managing failures within this framework to ensure reliable agent behavior.

What are common anti-patterns when creating SubAgent definitions?▼

Common SubAgent anti-patterns include improper context passing, incorrect tool selection, and poorly structured prompts. This skill identifies these anti-patterns and provides best practices and checklists to avoid them and ensure safe, auditable agent definitions.

How do I pass context between a main agent and a SubAgent?▼

Context passing between agents requires following specific patterns to ensure the SubAgent receives the necessary information. This skill provides recommended context-handling patterns and workarounds for MCP considerations to maintain data integrity.

How do I select the right tools for a SubAgent definition?▼

Tool selection for a SubAgent involves choosing the specific tools the agent needs to perform its task safely. This skill covers best practices for tool selection within the YAML frontmatter, ensuring the agent has appropriate permissions without being overly broad.

When should I not use a SubAgent for a task?▼

You should avoid using a SubAgent when the task does not require isolation, specialized tool access, or a distinct context window. This skill outlines limitations and helps you determine when a SubAgent is necessary versus when a simpler approach is better.