agent-builder

bsamiee 的头像作者 bsamiee

使用YAML前置元数据、工具权限、模型选择和系统提示结构创建和配置Claude Code代理文件(.claude/agents/*.md)。在构建新代理、配置代理前置元数据、设计发现触发器、设置工具权限、编写系统提示或选择代理模型时使用。

📖 中文导读:使用YAML前置元数据、工具权限、模型选择和系统提示结构创建和配置Claude Code代理文件(.claude/agents/*.md)。在构建新代理、配置代理前置元数据、设计发现触发器、设置工具权限、编写系统提示或选择代理模型时使用。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: agent-builder type: standard depth: base description: Creates and configures Claude Code agent files (.claude/agents/*.md) with YAML frontmatter, tool permissions, model selection, and system prompt structure. Use when building new agents, configuring agent frontmatter, designing discovery triggers, setting tool permissions, writing system prompts, or selecting agent models.

[H1][AGENT-BUILDER]

Dictum: Structured frontmatter and scoped tools enable discoverable agents.


Specialized execution contexts for main Claude agent invocation. Frontmatter controls discovery; markdown body encodes behavior.

Location: .claude/agents/ (project) or ~/.claude/agents/ (user). Project agents override user agents on name collision.

Tasks:

  1. Read index.md — Reference file listing for navigation
  2. Read frontmatter.md — Schema, triggers, syntax validation
  3. Read prompt.md — Structure patterns, constraint markers
  4. Read workflow.md — 5-phase creation process
  5. (prose) Load style-standards skill — Voice, formatting, constraints
  6. Execute per workflow — UNDERSTAND, ACQUIRE, RESEARCH, AUTHOR, VALIDATE
  7. Validate — Quality gate; see §VALIDATION

Templates: →agent.template.md — Standard agent scaffold.

[REFERENCE]: index.md — Complete reference file listing


[1][FRONTMATTER]

Dictum: Metadata enables discovery before load.


---
name: agent-name
description: >-
  Capability statement. Use when scenario-1, scenario-2, or scenario-3.
tools: Read, Glob, Grep
model: sonnet
skills: style-standards
---
[INDEX] [FIELD] [TYPE] [REQ] [CONSTRAINT]
[1] name string Yes Kebab-case, max 64 chars, match filename
[2] description string Yes Third person, active voice, trigger clause
[3] tools list No Comma-separated; omit = inherit all tools
[4] model enum No haiku, sonnet, opus, inherit
[5] skills list No Skill names agent can invoke

[2][DISCOVERY]

Dictum: Description quality determines invocation accuracy.


Reasoning matches description directly—no embeddings, no keyword matching.

[INDEX] [PATTERN] [EXAMPLE] [MECHANISM]
[1] "Use when" clause Use when building MCP servers Direct activation signal
[2] Proactive trigger Use proactively after code changes Encourages auto-invocation
[3] Imperative emphasis MUST BE USED before committing Strong delegation signal
[4] Enumerated list (1) creating, (2) modifying Parallel pattern matching
[5] Technology embed Python (FastMCP) or TypeScript Framework-specific match
[6] File extension working with PDF files (.pdf) Path-based triggering
[7] Catch-all or any other agent tasks Broadens applicability

[CRITICAL]:

  • [NEVER] Hedging words: might, could, should, probably.
  • [ALWAYS] Include "Use when" clause—3+ trigger scenarios.
  • [ALWAYS] Third person, active voice, present tense.

[3][TOOLS]

Dictum: Tool declarations scope permissions.


[INDEX] [PATTERN] [TOOLS] [USE_CASE]
[1] Read-only Read, Glob, Grep Analysis, review
[2] Write-capable Read, Edit, Write, Glob, Bash Implementation
[3] Orchestration Task, Read, Glob, TodoWrite Agent dispatch
[4] Full access (omit field) Inherits all tools

[IMPORTANT]:

  • [NEVER] Reference @path without Read in tools list.
  • [ALWAYS] Omit tools field for general-purpose agents.
  • [ALWAYS] Scope tools for specialized agents—reviewers require read-only.

[4][MODELS]

Dictum: Model selection balances capability against latency and cost.


[INDEX] [MODEL] [ALIAS] [STRENGTH] [LATENCY] [COST]
[1] opus opus Complex reasoning High High
[2] sonnet sonnet Balanced performance Medium Medium
[3] haiku haiku Fast, simple tasks Low Low
[4] inherit inherit Match main conversation Session Session
[INDEX] [TASK_TYPE] [MODEL]
[1] Multi-file scope opus
[2] Architectural decisions opus
[3] Standard development sonnet
[4] Fast lookups, filtering haiku

[IMPORTANT] Omit model field to inherit session default.


[5][SYSTEM_PROMPT]

Dictum: Structured prompts constrain execution.


Markdown body follows frontmatter. Body encodes agent behavior; structure determines effectiveness.


[6][NAMING]

Dictum: Naming conventions enable discovery.


[INDEX] [PATTERN] [EXAMPLE] [USE_CASE]
[1] Role-based code-reviewer Specialized function
[2] Action-based generating-commits Gerund form preferred
[3] Domain-specific react-specialist Technology expertise

[CRITICAL]:

  • [NEVER] Generic names: helper, processor, agent.
  • [NEVER] Underscores or mixed case.
  • [ALWAYS] Kebab-case—lowercase, hyphens only.
  • [ALWAYS] Filename matches name field exactly.

[7][VALIDATION]

Dictum: Validation gates prevent incomplete artifacts.


[VERIFY] Completion:

  • Workflow: All 5 phases executed (UNDERSTAND → VALIDATE).
  • Frontmatter: Valid YAML, description with "Use when" clause.
  • Tools: Matches type gate (readonly|write|orchestrator|full).
  • Prompt: Role line + H2 sections + constraint markers.
  • Quality: Kebab-case naming, filename matches name field.

[REFERENCE] Operational checklist: →validation.md