К основному содержанию
скилл CX Codex

agent-development · josiahsiegel — скилл для Claude Code: разработка агентов

Скилл agent-development помогает настроить frontmatter и системные промпты агентов для Claude Code. Пригодится при создании агента или разборе ситуации, когда он не срабатывает.

MIT 116 установок ★ 66 обновлён 2026-06-18

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add JosiahSiegel/claude-plugin-marketplace --skill agent-development -a claude-code
Открыть на GitHub

Что делает agent-development

Скилл задаёт структуру YAML-frontmatter и системного промпта агента. В ней описаны имя, модель inherit, список инструментов и формат description с условиями активации. Также есть шаблоны агентов и чек-лист проверки.

Примеры в description зависят от длины тела агента: для коротких и lean-оркестраторов они необязательны, а для текстов длиннее 3,000 слов требуются. Это важно при проверке: отсутствие примеров само по себе не означает ошибку. Скилл также помогает заменить устаревший agent: true на поле name.

Какие задачи решает

  • создать frontmatter нового агента
  • настроить условия активации агента
  • исправить агента, который не срабатывает
  • заменить устаревший флаг agent: true
  • проверить, нужны ли блочные примеры в description

Примеры запросов агенту

  • Помоги создать агента Claude Code и составить для него frontmatter.
  • Проверь, почему мой агент не срабатывает, и предложи правки.
  • Проверь description агента и скажи, нужны ли ему блоки <example>.

Как установить agent-development

1Через Skills CLI (Vercel)

npx skills add JosiahSiegel/claude-plugin-marketplace --skill agent-development -a claude-code

2Вручную: положить файлы

~/.claude/skills/agent-development/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/agent-development/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об agent-development

Как установить agent-development в Claude Code?

Выполните npx skills add JosiahSiegel/claude-plugin-marketplace --skill agent-development -a claude-code. Файл скилла появится по пути ~/.claude/skills/agent-development/SKILL.md.

Что делает скилл agent-development?

Он помогает создавать и проверять конфигурацию агентов Claude Code: frontmatter, системный промпт и условия активации. Включает шаблоны и чек-лист.

Всегда ли агенту нужны блоки <example>?

Нет. Для тела короче 2,500 слов примеры необязательны; если текст превышает 3,000 слов, нужны 3–5 блоков и разбиение агента на части.

Исходный текст

SKILL.md · MIT
---
name: agent-development
description: |
  Canonical guide to authoring Claude Code agent frontmatter and system prompts.
  PROACTIVELY activate for: (1) creating a new agent, (2) adding an agent to a plugin, (3) writing agent frontmatter, (4) designing a system prompt, (5) configuring <example> trigger blocks, (6) restricting tools, (7) setting model inherit, (8) migrating deprecated agent true flag, (9) fixing "agent never triggers", (10) ensuring skills have agent trigger coverage.
  Provides: agent templates, lean-orchestrator pattern, and validation checklist.
---

# Agent Development for Claude Code Plugins

## Overview

Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Each agent is a markdown file in the `agents/` directory with YAML frontmatter defining its configuration and a markdown body serving as its system prompt.

## Canonical agent frontmatter template (MANDATORY shape)

This is the template every new agent MUST follow. Deviating from this shape is the #1 cause of agents that never trigger.

```yaml
---
name: my-agent                                    # REQUIRED: kebab-case, 3-50 chars, alphanumeric start/end
model: inherit                                    # REQUIRED: always `inherit` unless you have a hard reason
color: blue                                       # RECOMMENDED: one of blue/cyan/green/yellow/magenta/red
tools: Read, Write, Edit, Glob, Grep, Bash        # RECOMMENDED: minimal set; omit for full access
description: |
  One-sentence summary of what the agent does. PROACTIVELY activate for: (1) concrete trigger, (2) concrete trigger, ..., (N) concrete trigger. Provides: comma-separated capability nouns.

  <example>
  Context: Realistic situation where the agent should fire
  user: "A realistic user quote -- the kind of thing someone would actually type"
  assistant: "Short 1-2 sentence response. Mention loading a specific skill if relevant."
  <commentary>Triggers for specific-keyword-1, specific-keyword-2, specific-keyword-3</commentary>
  </example>

  <example>
  Context: Another realistic situation covering a different capability
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A debugging / troubleshooting scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>

  <example>
  Context: A "when to pick this vs. that" scenario
  user: "..."
  assistant: "..."
  <commentary>Triggers for ...</commentary>
  </example>
---

You are [role] specializing in [domain]. [Lean orchestrator body -- see "Lean Orchestrator Pattern" below.]
```

### Hard rules for the frontmatter

1. **`name:` is required.** Do NOT use the deprecated `agent: true` flag — that pattern is legacy and results in an unnamed agent that cannot be referenced or routed to reliably. If you find `agent: true` in an existing file, replace it with `name: <kebab-name-from-filename>`.
2. **`model: inherit` is required.** Never hard-code a model unless the agent has a documented capability requirement.
3. **`description:` MUST include the enumerated `PROACTIVELY activate for: (1)... (2)... (N)...` pattern AND a `Provides: ...` capability list.** A description that only says "Use this agent for help with X" will not route reliably.
4. **`<example>` blocks are conditional, not unconditional.** Whether the description needs `<example>` blocks depends on the agent's body word count — see **"Example-block requirement by agent body size"** below. Lean orchestrators deliberately omit them; fat agents need them. Do not blanket-require examples on every agent.
5. **Use `description: |` (YAML block scalar)** whenever the description spans multiple lines or contains `<example>` blocks. A folded scalar (`>`) or implicit flow scalar will mangle the examples.
6. **Do NOT put cross-cutting boilerplate (Windows path rules, documentation policy, etc.) inside the YAML `description:` block.** That text is used for routing-match, and boilerplate that appears in many agents poisons the signal. Put it in the markdown body under a clearly named `## Windows file path requirements` section (or similar) instead.

### Example-block requirement by agent body size (UNIFIED RULE)

The number of `<example>` blocks a description needs is a function of the agent's markdown body word count. This rule reconciles two earlier conflicting recommendations ("always add 4-6 examples" vs. "lean orchestrators don't need examples") into a single tier table that authoring guidance, the canonical checklist, and `scripts/validate_plugins.py` all share.

| Agent body word count | Tier | Example-block requirement |
|---|---|---|
| < 1,500 words | Sub-target | Optional |
| 1,500-2,500 words | **Lean orchestrator (target band)** | **Optional, often omitted by design** |
| 2,500-3,000 words | Above-target | **Recommended (3-5)** |
| > 3,000 words | Oversized | **Required (3-5) AND extraction mandatory** |

The validator only flags "missing examples" when the body crosses 2,500 words (`AGENT_EXAMPLES_THRESHOLD_WORDS`). Lean orchestrators under that threshold pass cleanly without examples — that absence is by design.

**Authoring distilled:** decide lean-orchestrator vs. fat-agent first; if lean, the `PROACTIVELY activate for:` enumeration carries routing and examples are not required. When refactoring fat -> lean, stripping examples is a legitimate part of the refactor. When auditing, compute body word count BEFORE recommending example-block fixes — see "Pre-recommendation intent check" below.

### Deprecated / broken patterns to migrate

| Broken pattern | What it does | Fix |
|---|---|---|
| `agent: true` (no `name:`) | Agent cannot be named/routed reliably | Replace with `name: <kebab-name>` |
| `description:` without `<example>` blocks (agent body > 2,500 words) | Fat agent that routes ambiguously without examples | Add 3-5 `<example>` blocks OR split into orchestrator + skills (preferred) |
| `description:` with "Use this agent for X" prose only | Vague routing, poor trigger | Rewrite with `PROACTIVELY activate for: (1)...` enumeration |
| Windows boilerplate inside YAML `description:` | Pollutes routing signal | Move to `## Windows file path requirements` in body |
| `model:` missing or hard-coded (e.g. `model: sonnet`) | Fails to inherit session model | Set `model: inherit` |
| Single `<example>` block with full code in `assistant:` | Dilutes matching, bloats description | Keep assistant replies to 1-2 sentences; put code in skills |

## Frontmatter Fields Reference

Detailed rules for each frontmatter field (`name`, `description`, `model`, `color`, `tools`) live in `references/frontmatter-fields-reference.md`. Highlights:

- **name** — kebab-case, 3-50 chars, alphanumeric start/end; role-based convention (`code-reviewer`, `domain-expert`).
- **description** — most critical field; must include `PROACTIVELY activate for: (1)... (N)...` enumeration and `Provides: ...` capability list. `<example>` blocks gated by the body-word-count tier table above.
- **model** — `inherit` is the default; only deviate with a documented capability reason.
- **color** — `blue`/`cyan` (analysis), `green` (generation), `yellow` (validation), `red` (critical/security), `magenta` (creative/architecture).
- **tools** — principle of least privilege; common: `Read, Write, Edit, Grep, Glob, Bash, WebSearch, WebFetch, Skill, Agent`. MCP tools as `mcp__server__tool`.

Load `references/frontmatter-fields-reference.md` when authoring or auditing a real agent.


## System Prompt Design

The markdown body becomes the agent's system prompt. Write in **second person** ("You are...", "You will..."). Required sections: Core Responsibilities, Process, Quality Standards, Output Format, Edge Cases. DO be specific and define output clearly; DON'T write in first person, be vague, or embed domain knowledge that belongs in skills. Full template + DO/DON'T list: `references/design-principles-and-mistakes.md`.

## Lean Orchestrator Pattern (CRITICAL)

An agent body must be a **lean orchestrator**, NOT a domain knowledge dump. The agent delegates to skills for detailed knowledge.

### Agent Body Size Limits

| Metric | Target | Hard Maximum |
|--------|--------|-------------|
| Word count | 1,500-2,500 words | 3,000 words |
| Character count | ~10,000-15,000 chars | 20,000 chars |

### What Belongs in the Agent Body

| Section | Required | Purpose |
|---------|----------|---------|
| Role identity | Yes | "You are [role] specializing in [domain]" |
| Skill activation rules | Yes | Topic-to-skill mapping table |
| High-level process | Yes | Design/workflow steps |
| Output format | Yes | What to include in responses |
| Brief service summaries | Optional | 2-3 sentences per area to help decide which skill to load |
| Edge cases / troubleshooting tips | Optional | Quick reference only |

### What Does NOT Belong in the Agent Body

- **Detailed domain knowledge** — belongs in skills
- **Complete CLI/API references** — belongs in skill references/
- **Full code examples** — belongs in skill examples/
- **Duplicated skill content** — if it's in a skill, do NOT repeat it in the agent

### Anti-Pattern: Content Duplication

**NEVER duplicate content between the agent body and skills.** This is the most common mistake and causes massive context bloat.

**Bad:** Agent body contains a full "Plugin.json Schema" section AND the plugin-master skill also contains it.
**Good:** Agent body says "For plugin.json schema details, load `plugin-master:plugin-master`" and keeps only a 1-sentence summary.

### Lean Orchestrator Template

```markdown
You are [role] specializing in [domain].

## Skill Activation - CRITICAL
[Topic-to-skill mapping table -- this is the heart of the agent]

## Core Responsibilities
[2-5 bullet points on what this agent does]

## Process
[5-7 step workflow for handling user requests]

## Quality Standards
[Brief checklist -- 5-10 items]

## Output Format
[What to include in responses]
```

### Description Size Limits

Agent descriptions should be concise and effective:

| Element | Guideline |
|---------|-----------|
| Intro text | 1-2 sentences on when to trigger |
| Example blocks | 3-7 blocks covering diverse scenarios |
| Total description | Should fit naturally — focus on quality trigger examples over length |

## Agent Design Principles & Common Mistakes

Detailed design principles (agent-first design, single responsibility, skill integration, preventing trigger phrase overlap) and the full Common-Mistakes table live in `references/design-principles-and-mistakes.md`. Core distillation:

- One expert agent per plugin, named `{domain}-expert`. Users converse, not navigate menus.
- Single responsibility per agent; multi-topic needs become skills, not new agents.
- Skill activation instructions belong in the system prompt.
- Trigger-phrase overlap between skills must be audited and disambiguated in the skill activation table.

## Validation Checklist

Before finalizing an agent:

- [ ] Name: 3-50 chars, lowercase, hyphens, starts/ends alphanumeric
- [ ] Description: includes `PROACTIVELY activate for:` enumeration and `Provides:` capability list
- [ ] `<example>` blocks present **if and only if** required by the agent's body word count (see "Example-block requirement by agent body size" tier table). Lean orchestrators under 2,500 words are exempt.
- [ ] **If examples ARE present**, every skill the agent delegates to has at least one example that routes to it
- [ ] **No trigger phrase overlap**: no ambiguous keyword claimed by multiple skills without disambiguation
- [ ] Model: set to `inherit` (unless specific need)
- [ ] Color: appropriate for agent function
- [ ] Tools: restricted to minimum needed (or omitted for full access)
- [ ] Frontmatter: valid YAML with all required fields
- [ ] File location: `agents/agent-name.md`

## Testing

1. Write agent with specific triggering examples
2. Use similar phrasing to examples in your test queries
3. Verify Claude loads the agent for matching requests
4. Test that the agent follows its defined process
5. Check output matches defined format
6. Test edge cases mentioned in system prompt

## Common Mistakes

Full table (vague descriptions, model overrides, tool over-grants, cross-cutting boilerplate in every skill, re-adding examples to a lean orchestrator, etc.) lives in `references/design-principles-and-mistakes.md`.

## Pre-recommendation intent check (audit caveat)

Before recommending a fix to an existing agent — especially one that involves re-adding content that has been stripped — confirm the apparent defect is not the result of a deliberate prior decision. Example-block stripping during lean-orchestrator refactors is routine and intentional; a follow-up audit that flags "agent missing examples" without checking word count produces a false-positive backlog of contradictory remediation work.

**Short rule:** before listing any agent finding, run the three-question intent check (size tier, git log, validator output). Only if all three say "real defect" should it appear in the audit report.

Full check, with rationale, expanded list of stripped-on-purpose patterns, and the authoring-vs-auditing contrast: see `references/validation-and-audits.md`.

## Validation by `scripts/validate_plugins.py`

The repo ships a read-only quality gate at `scripts/validate_plugins.py`. It is the single source of truth for what counts as "good" agent frontmatter in this marketplace. When the validator and this skill disagree, the validator wins.

**Quick invocations:**

```bash
python scripts/validate_plugins.py                    # whole marketplace
python scripts/validate_plugins.py --plugin my-plugin # one plugin
python scripts/validate_plugins.py --strict           # warnings fail the build
```

The complete rule tables (agent-level, skill-level, plugin-level) plus the list of known validator gaps live in `references/validation-and-audits.md`.

© JosiahSiegel · MIT · JosiahSiegel/claude-plugin-marketplace

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →

Сначала — agent-development от других авторов.

agent-development официальный Anthropic Скилл agent-development для Claude Code, который учит создавать субагентов: описывает структуру файла, frontmatter, системный промпт и условия запуска. Активируется, когда агент просит добавить субагента или описать его поведение. CX Codex +1 7 353установок prompt-engineer davila7 Скилл prompt-engineer структурирует системные промпты, настраивает примеры few-shot и цепочки рассуждений для приложений на базе LLM. Пригодится при составлении надёжных инструкций для моделей. CX Codex +1 591установок Creed Space nell MCP-сервер Creed Space подключает к ИИ-агентам систему конституционных правил и готовые персоны. Помогает проверять ответы и запросы на соответствие заданным принципам. CX Codex +1 10 491установок prompt-engineering giuseppe-trisciuoglio Скилл prompt-engineering для Claude Code помогает писать, отлаживать и проверять промпты для LLM. Охватывает few-shot-примеры, системные инструкции и шаблоны. CX Codex +1 4 200установок Prompt Engineer официальный github Субагент Prompt Engineer разбирает каждый ввод как промпт, показывает оценку и выдаёт переработанную инструкцию для языковой модели. CX Codex +1 ★ 41 430звёзд репо baoyu-format-markdown JimLiu Скилл baoyu-format-markdown форматирует plain text и Markdown: добавляет структуру, frontmatter, заголовки, списки и код. Результат сохраняется в {filename}-formatted.md. CX Codex +1 28 800установок okf-knowledge-base Inkeep Скилл okf-knowledge-base для Claude Code помогает создавать и проверять наборы знаний в формате OKF. Он включается при работе с OKF, предупреждениями плагина okf и выбором типов или ссылок. CX Codex +1 9 400установок

Из того же набора96

Весь набор →
viral-video-hook-templates Скилл viral-video-hook-templates для Claude Code содержит 10 шаблонов хуков и фильтры FFmpeg для первых 3 секунд видео. Помогает тестировать варианты заставок и удерживать внимание зрителей. CX Codex +1 131установок markdown-style Скилл markdown-style проверяет Markdown в два прохода: сначала синтаксис по канону, потом стиль. Показывает находки построчно и правит только то, что вы одобрили. CX Codex +1 125установок ffmpeg-karaoke-animated-text Скилл ffmpeg-karaoke-animated-text помогает ассистенту собирать команды FFmpeg и разметку ASS для караоке, титров и анимации текста. Пригодится при монтаже роликов и клипов. CX Codex +1 121установок skill-development Скилл skill-development для Claude Code описывает правила SKILL.md для плагинов Claude: фронтматтер, структуру каталогов и исправление скиллов, которые не срабатывают. CX Codex +1 116установок ffmpeg-stabilization-360 Скилл ffmpeg-stabilization-360 для Claude Code обрабатывает тряску видео и конвертирует проекции 360/VR. Активируется для стабилизации, коррекции объектива и эффектов панорамирования и зума. CX Codex +1 115установок viral-video-long-form Скилл viral-video-long-form для Claude Code помогает планировать длинные YouTube-видео и улучшать их SEO, удержание аудитории и обложки. Активируется для стратегии канала, структуры ролика и разбора аналитики. CX Codex +1 114установок power-query-m Помогает писать Power Query M, разбирать query folding и собирать ETL-преобразования. Охватывает запросы, параметры и коннекторы. CX Codex +1 114установок adf-ml-analytics Скилл adf-ml-analytics для Claude Code содержит рецепты batch-скоринга Azure ML, запуска Databricks и архивации SQL в Storage через Azure Data Factory. Для новых пайплайнов предлагает batch-эндпоинты SDK v2 вместо SDK v1. CX Codex +1 113установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой