agent-development

分类: 工具与效率 | 上传者: OshanKHZ | 下载: 0 | 版本: v1.0（最新）

生成 Claude Code 插件代理 .md 文件：编写 YAML frontmatter（名称、模型、颜色、工具、挂钩、disallowedTools），制作系统提示，并创建带有上下文和注释的触发示例块。根据命名、长度和格式限制验证代理结构。当用户要求创建代理、添加代理、编写子代理、配置代理前端、设计代理系统提示、设置代理工具或颜色、构建自治代理或添加代理挂钩时使用。 --- # Claude 代码插件的代理开发代理是带有 YAML frontmatter 的自治 Markdown 文件，可以独立处理多步骤任务。代理人是为了自主工作；命令用于用户启动的操作。 ## 工作流程 1. 定义代理目的和触发条件 2. 创建 `agents/agent-name.md`，其中包含 frontmatter + 系统提示正文 3. 在描述中包含 2-4 个 `<example>` 块 4. 验证结构（参见下面的约束） 5. 使用真实场景测试触发 6. 如果验证失败：检查错误恢复表，修复，重新验证 ## 代理文件模板 ```markdown ---

更新日志: Source: GitHub https://github.com/OshanKHZ/cc-swiss-knife

目录结构

当前层级: tree/main/plugins/claude-code-forge/skills/agent-development/

📁 examples/
- 📄 agent-creation-prompt.md 9.2 KB
- 📄 complete-agent-examples.md 13.8 KB
📁 references/
- 📄 agent-creation-system-prompt.md 8.7 KB
- 📄 system-prompt-design.md 9.8 KB
- 📄 triggering-examples.md 11.3 KB
📁 scripts/
- 📄 validate-agent.sh 5.7 KB
📄 SKILL.md 6.3 KB

SKILL.md

---
name: agent-development
description: >
  Generates Claude Code plugin agent .md files: writes YAML frontmatter (name, model,
  color, tools, hooks, disallowedTools), crafts system prompts, and creates triggering
  example blocks with context and commentary. Validates agent structure against naming,
  length, and format constraints. Use when the user asks to create an agent, add an
  agent, write a subagent, configure agent frontmatter, design agent system prompts,
  set agent tools or colors, build an autonomous agent, or add agent hooks.
---

# Agent Development for Claude Code Plugins

Agents are autonomous markdown files with YAML frontmatter that handle multi-step tasks independently. Agents are for autonomous work; commands are for user-initiated actions.

## Workflow

1. Define agent purpose and triggering conditions
2. Create `agents/agent-name.md` with frontmatter + system prompt body
3. Include 2-4 `<example>` blocks in description
4. Validate structure (see constraints below)
5. Test triggering with real scenarios
6. If validation fails: check error recovery table, fix, re-validate

## Agent File Template

```markdown
---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation]
user: "[Request]"
assistant: "[Response before triggering]"
<commentary>[Why this agent triggers]</commentary>
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary task]
2. [Secondary task]

**Process:**
1. [Step 1]
2. [Step 2]

**Output Format:**
[What to return and how]

**Edge Cases:**
- [Case]: [How to handle]
```

## Frontmatter Reference

| Field | Required | Format | Constraints |
|-------|----------|--------|-------------|
| `name` | Yes | `lowercase-hyphens` | 3-50 chars, start/end alphanumeric, no underscores |
| `description` | Yes | Text + `<example>` blocks | 10-5000 chars, must include triggering conditions |
| `model` | Yes | `inherit\|sonnet\|opus\|haiku` | Use `inherit` unless specific need |
| `color` | Yes | `blue\|cyan\|green\|yellow\|magenta\|red` | Distinct per plugin |
| `tools` | No | Array of tool names | Least-privilege principle; default: all tools |
| `hooks` | No | Array of hook configs | See hooks section |
| `disallowedTools` | No | Array with `Task(AgentName)` | Prevents specific agents from running |

**Color conventions:** blue/cyan = analysis/review, green = success, yellow = validation, red = security, magenta = creative.

**Common tool sets:**
- Read-only: `["Read", "Grep", "Glob"]`
- Code generation: `["Read", "Write", "Grep"]`
- Testing: `["Read", "Bash", "Grep"]`

## Description Field

The description must include triggering conditions and 2-4 `<example>` blocks. Each example needs: `Context`, `user` message, `assistant` response, and `<commentary>` explaining why the agent triggers.

Cover different triggering types across examples:
- **Explicit**: user directly requests the agent's function
- **Proactive**: agent triggers after relevant work without explicit request
- **Implicit**: user implies need without stating it directly

See `references/triggering-examples.md` for detailed patterns and templates.

## Hooks

Agent-level hooks scoped to agent lifecycle:

```yaml
hooks:
  - type: PreToolUse    # Validate before agent uses tools
    once: true          # Runs only once per invocation
  - type: PostToolUse   # React to agent tool results
  - type: Stop          # Cleanup when agent completes
```

Hooks inherit agent context. No command/prompt field needed. See `../hook-development/` for full documentation.

## disallowedTools

Prevent specific agents from being invoked:

```yaml
disallowedTools: ["Task(SWEAgent)", "Task(ExperimentalAgent)"]
```

Also configurable in settings.json and via `--disallowedTools` CLI flag.

## System Prompt Guidelines

The markdown body below the frontmatter becomes the agent's system prompt. Write in second person ("You are...", "You will...").

**Required sections:** Role description, Core Responsibilities, Process steps, Output Format.
**Recommended sections:** Quality Standards, Edge Cases.

**Keep prompts under 10,000 characters.** Optimal range: 500-3,000 characters. If longer, extract reference data into separate files.

See `references/system-prompt-design.md` for analysis, generation, validation, and orchestration prompt patterns.

## Agent Organization

```
plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md
```

All `.md` files in `agents/` are auto-discovered. Agents are namespaced automatically: `agent-name` (single plugin) or `plugin:subdir:agent-name` (with subdirectories).

## Best Practices

- Include 2-4 concrete `<example>` blocks with varied phrasings in description
- Use `inherit` for model unless a specific model is required
- Apply least-privilege tool access
- Assign distinct colors per agent within a plugin
- Write specific, structured system prompts with clear process steps
- Define output format explicitly
- Test triggering with real scenarios before shipping

## Error Recovery

| Problem | Fix |
|---------|-----|
| Agent not triggering | Add more `<example>` blocks with varied phrasings; verify keywords match user intent |
| Name validation fails | Ensure 3-50 chars, lowercase + hyphens only, starts/ends alphanumeric |
| System prompt too long | Keep under 10,000 chars; extract reference data into separate files |
| Agent uses wrong tools | Add explicit `tools` array; verify tool names match exactly |
| Agent color not showing | Confirm color is one of: blue, cyan, green, yellow, magenta, red |
| Description too vague | Add triggering conditions and concrete `<example>` blocks with `<commentary>` |
| Agent triggers incorrectly | Make examples more specific; add negative-case commentary |

## Additional Resources

- `references/system-prompt-design.md` - Prompt patterns for analysis, generation, validation, orchestration agents
- `references/triggering-examples.md` - Example formats and triggering best practices
- `references/agent-creation-system-prompt.md` - The exact prompt from Claude Code
- `examples/agent-creation-prompt.md` - AI-assisted agent generation template
- `examples/complete-agent-examples.md` - Full agent examples for different use cases
- `scripts/validate-agent.sh` - Validate agent file structure

登录后下载/点赞/收藏 ❤ 5 | ★ 0

agent-development

目录结构

SKILL.md

举报内容

提示