claude-extensibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Claude Code Extensibility

Claude Code 扩展性

CRUD operations for agents, skills, and output styles following Anthropic best practices.

遵循Anthropic最佳实践的Agent、Skill和输出样式的CRUD操作。

Related Skills

Core Principles

核心原则

Simplicity: Direct tool calls, avoid complex abstractions
Focus: Single, clear responsibility per extension
Conciseness: Target <500 lines, use progressive disclosure
Efficiency: Optimize for token usage and response time

简洁性：直接调用工具，避免复杂抽象
专注性：每个扩展承担单一、明确的职责
精简性：目标代码行数<500，采用渐进式披露
高效性：优化令牌使用量和响应时间

Extension Types

扩展类型

Type	Invocation	Purpose	Location
Agents	Task tool	Specialized sub-processes	`.claude/agents/`
Skills	Model-invoked (autonomous)	Domain knowledge	`.claude/skills/{name}/`
Output Styles	`/output-style` command	Modify main agent behavior	`.claude/output-styles/`

类型	调用方式	用途	存储位置
Agent	Task工具	专用子流程	`.claude/agents/`
Skill	模型自主调用	领域知识封装	`.claude/skills/{name}/`
输出样式	`/output-style` 命令	修改主Agent行为	`.claude/output-styles/`

Agent Development

Agent开发

Reference:

references/agent-development.md

- Full YAML structure, model/tool selection, system prompt patterns, optimization techniques.

参考文档：

references/agent-development.md

- 完整YAML结构、模型/工具选择、系统提示词模式、优化技巧。

Quick Start: Agent

Agent快速入门

yaml

---
name: agent-name
description: Use this agent when [use case]. Use PROACTIVELY for [triggers].\n\nExamples:\n<example>\nContext: [situation]\nuser: [request]\nassistant: [response]\n<commentary>[reasoning]</commentary>\n</example>
tools: Grep, Glob, Read, Bash
model: haiku
permissionMode: default
skills: skill-name
---

yaml

---
name: agent-name
description: 在[使用场景]下使用该Agent。在[触发条件]下主动调用。\n\n示例:\n<example>\n场景: [具体情境]\n用户: [请求内容]\n助手: [响应内容]\n<commentary>[推理过程]</commentary>\n</example>
tools: Grep, Glob, Read, Bash
model: haiku
permissionMode: default
skills: skill-name
---

Agent Name

Agent名称

Brief mission statement.

简短的使命说明。

Core Strategy

核心策略

1. Phase Name

1. 阶段名称

Approach and techniques

<format> Expected output structure </format> ```

方法与技术

<format> 预期输出结构 </format> ```

YAML Fields

YAML字段说明

Field	Required	Description
`name`	Yes	Lowercase, hyphens (e.g., `code-reviewer` )
`description`	Yes	Single line with `\n` for newlines, include examples
`tools`	No	Comma-separated; inherits all if omitted
`model`	No	`haiku` , `sonnet` , `opus` , `inherit` (default: sonnet)
`permissionMode`	No	`default` , `acceptEdits` , `bypassPermissions` , `plan` , `ignore`
`skills`	No	Comma-separated skill names to auto-load

字段	是否必填	描述
`name`	是	小写字母，连字符分隔（例如： `code-reviewer` ）
`description`	是	单行文本，用 `\n` 换行，包含示例
`tools`	否	逗号分隔；省略时继承所有工具
`model`	否	`haiku` , `sonnet` , `opus` , `inherit` （默认值：sonnet）
`permissionMode`	否	`default` , `acceptEdits` , `bypassPermissions` , `plan` , `ignore`
`skills`	否	逗号分隔的自动加载Skill名称

Model Selection

模型选择

Model	Use When	Target Time
`haiku`	Fast tasks, exploration, search	< 3s
`sonnet`	Balanced, most use cases	< 10s
`opus`	Complex reasoning, architecture	< 30s
`inherit`	Match main conversation model	varies

模型	适用场景	目标响应时间
`haiku`	快速任务、探索、搜索	< 3秒
`sonnet`	平衡型，适用于大多数场景	< 10秒
`opus`	复杂推理、架构设计	< 30秒
`inherit`	匹配主对话模型	可变

Built-in Subagents

内置子Agent

Agent	Model	Tools	Purpose
`general-purpose`	Sonnet	All	Complex research, multi-step operations
`plan`	Sonnet	Read, Glob, Grep, Bash	Research in plan mode
`Explore`	Haiku	Read-only	Fast codebase search (quick/medium/very thorough)

Agent	模型	工具	用途
`general-purpose`	Sonnet	全部	复杂研究、多步骤操作
`plan`	Sonnet	Read, Glob, Grep, Bash	计划模式下的研究
`Explore`	Haiku	只读	快速代码库搜索（快速/中等/深度）

Agent Locations

Agent存储位置

Location	Scope	Priority
`.claude/agents/`	Project	Highest
`~/.claude/agents/`	User (all projects)	Lower
Plugin `agents/`	Plugin-specific	Varies
`--agents` CLI flag	Session only	Medium

位置	作用范围	优先级
`.claude/agents/`	项目级	最高
`~/.claude/agents/`	用户级（所有项目）	较低
插件 `agents/`	插件专属	可变
`--agents` CLI参数	会话级	中等

CLI-Defined Agents

CLI定义的Agent

bash

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

bash

claude --agents '{
  "code-reviewer": {
    "description": "专业代码评审员。代码变更后主动调用。",
    "prompt": "你是一名资深代码评审员...",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Resumable Agents

可恢复Agent

Continue previous conversations:

Each execution gets unique
```
agentId
```
Transcript stored in
```
agent-{agentId}.jsonl
```
Resume with previous
```
agentId
```
to continue with full context

继续之前的对话：

每次执行都会生成唯一的
```
agentId
```
对话记录存储在
```
agent-{agentId}.jsonl
```
中
使用之前的
```
agentId
```
恢复对话，保留完整上下文

Skill Development

Skill开发

Reference:

references/skill-development.md

- Full structure, trigger patterns, hook system.

参考文档：

references/skill-development.md

- 完整结构、触发模式、钩子系统。

Quick Start: Skill

Skill快速入门

yaml

---
name: skill-name
description: "[What it does]. [Technologies]. Capabilities: [list]. Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."
allowed-tools: Read, Grep, Glob
---

yaml

---
name: skill-name
description: "[功能描述]。[涉及技术]。能力：[列表]。操作：[动词]。关键词：[触发词]。适用场景：[场景]。"
allowed-tools: Read, Grep, Glob
---

Skill Name

Skill名称

Purpose

用途

What this skill helps with

该Skill能解决的问题

When to Use

适用场景

Specific scenarios and conditions

具体场景与触发条件

Key Information

关键信息

Guidance, patterns, examples

undefined

指导方案、模式、示例

undefined

YAML Fields

YAML字段说明

Field	Required	Description
`name`	Yes	Lowercase, hyphens, max 64 chars
`description`	Yes	WHAT + WHEN format, max 1024 chars, quoted
`allowed-tools`	No	Restrict tool access (security)

字段	是否必填	描述
`name`	是	小写字母，连字符分隔，最长64字符
`description`	是	WHAT + WHEN格式，最长1024字符，需加引号
`allowed-tools`	否	限制工具访问权限（安全控制）

Description Format (WHAT + WHEN)

描述格式（WHAT + WHEN）

Structure:

"[Core purpose]. [Technologies/Stack]. Capabilities: [list]. Actions: [verbs]. Keywords: [triggers]. Use when: [scenarios]."

Good example:

yaml

description: "Extract text and tables from PDF files, fill forms, merge documents. Formats: .pdf. Tools: pypdf, pdfplumber. Capabilities: text extraction, form filling, document merging. Actions: extract, fill, merge PDFs. Keywords: PDF, form, document, pypdf, pdfplumber. Use when: working with PDF files, extracting data from documents, filling PDF forms."

Bad examples:

yaml

description: Helps with documents  # Too vague
description: PDF skill  # Missing WHEN triggers

结构：

"[核心用途]。[技术栈]。能力：[列表]。操作：[动词]。关键词：[触发词]。适用场景：[场景]。"

优秀示例：

yaml

description: "从PDF文件提取文本和表格、填写表单、合并文档。支持格式：.pdf。工具：pypdf, pdfplumber。能力：文本提取、表单填写、文档合并。操作：提取、填写、合并PDF。关键词：PDF、表单、文档、pypdf、pdfplumber。适用场景：处理PDF文件、从文档提取数据、填写PDF表单。"

反面示例：

yaml

description: 处理文档  # 过于模糊
description: PDF技能  # 缺少触发场景

Tool Access Control

工具权限控制

Restrict Claude's tools with

allowed-tools

yaml

---
name: safe-reader
description: "Read-only file access. Use when viewing code without modifications."
allowed-tools: Read, Grep, Glob
---

使用

allowed-tools

限制Claude的工具访问：

yaml

---
name: safe-reader
description: "只读文件访问。查看代码但不修改时使用。"
allowed-tools: Read, Grep, Glob
---

Skill Locations

Skill存储位置

Location	Scope
`.claude/skills/{name}/SKILL.md`	Project (shared via git)
`~/.claude/skills/{name}/SKILL.md`	User (all projects)
Plugin `skills/`	Plugin-bundled

位置	作用范围
`.claude/skills/{name}/SKILL.md`	项目级（通过Git共享）
`~/.claude/skills/{name}/SKILL.md`	用户级（所有项目）
插件 `skills/`	插件内置

Skill Structure

Skill目录结构

my-skill/
├── SKILL.md (required)
├── references/ (optional - detailed docs)
├── scripts/ (optional - utilities)
└── templates/ (optional - templates)

my-skill/
├── SKILL.md (必填)
├── references/ (可选 - 详细文档)
├── scripts/ (可选 - 实用工具)
└── templates/ (可选 - 模板)

Output Styles

输出样式

Modify Claude Code's main agent behavior.

修改Claude Code主Agent的行为。

Quick Start: Output Style

输出样式快速入门

markdown

---
name: My Custom Style
description: Brief description of behavior
keep-coding-instructions: true
---

markdown

---
name: My Custom Style
description: 行为简要说明
keep-coding-instructions: true
---

Custom Style Instructions

自定义样式说明

You are an interactive CLI tool that helps users...

你是一个交互式CLI工具，帮助用户...

Specific Behaviors

具体行为

[Define assistant behavior...]

undefined

[定义助手行为...]

undefined

YAML Fields

YAML字段说明

Field	Purpose	Default
`name`	Display name	Filename
`description`	UI description	None
`keep-coding-instructions`	Retain coding instructions	`false`

字段	用途	默认值
`name`	显示名称	文件名
`description`	UI展示描述	无
`keep-coding-instructions`	保留编码指令	`false`

Built-in Styles

内置样式

Default: Standard software engineering
Explanatory: Educational insights between tasks
Learning: Collaborative with
```
TODO(human)
```
markers

Default：标准软件工程风格
Explanatory：任务间插入教育性说明
Learning：协作式风格，带有
```
TODO(human)
```
标记

Output Style Locations

输出样式存储位置

User:
```
~/.claude/output-styles/
```
Project:
```
.claude/output-styles/
```

用户级：
```
~/.claude/output-styles/
```
项目级：
```
.claude/output-styles/
```

Usage

使用方法

bash

/output-style              # Access menu
/output-style explanatory  # Switch directly

bash

/output-style              # 打开菜单
/output-style explanatory  # 直接切换

Testing

测试

Key Question: Does it activate when expected?

核心问题：是否在预期场景下激活？

Agent Testing:

bash

Task(
  subagent_type="agent-name",
  description="Test task",
  prompt="Detailed test prompt"
)

Skill Testing:

Test prompts that SHOULD trigger
Test prompts that should NOT trigger
Debug with:
```
claude --debug
```

Agent测试：

bash

Task(
  subagent_type="agent-name",
  description="测试任务",
  prompt="详细测试提示词"
)

Skill测试：

测试应该触发的提示词
测试不应该触发的提示词
使用
```
claude --debug
```
调试

Common Workflows

常见工作流

Create Agent

创建Agent

Create
```
.claude/agents/{name}.md
```
Write YAML frontmatter (name, description, tools, model)
Write system prompt (<500 lines)
Test with Task tool
Optimize based on performance

创建
```
.claude/agents/{name}.md
```
编写YAML前置元数据（名称、描述、工具、模型）
编写系统提示词（<500行）
使用Task工具测试
根据性能优化

Create Skill

创建Skill

Create
```
.claude/skills/{name}/SKILL.md
```
Write YAML frontmatter with WHAT + WHEN description
Write content (<500 lines)
Use
Skill("prompt-enhancer")
to improve prompt
Add reference files for detailed content
Test: Does it activate when expected?

创建
```
.claude/skills/{name}/SKILL.md
```
编写WHAT + WHEN格式的YAML前置元数据
编写内容（<500行）
使用
Skill("prompt-enhancer")
优化提示词
添加参考文件存放详细内容
测试：是否在预期场景下激活？

Optimize Extension

优化扩展

Measure baseline (lines, token usage, response time)
Move details to reference files
Use
Skill("prompt-enhancer")
to improve prompts
Remove second-person voice
Use code blocks over prose
Add XML structure
Test and verify improvements

测量基准指标（行数、令牌使用量、响应时间）
将详细内容移至参考文件
使用
Skill("prompt-enhancer")
优化提示词
移除第二人称表述
用代码块替代散文式说明
添加XML结构
测试并验证优化效果

Best Practices

最佳实践

Anthropic Guidelines

Anthropic指南

✅ 500-line rule: Keep SKILL.md and agent prompts under 500 lines ✅ Progressive disclosure: Use reference files for detailed content ✅ Proactive language: Include "use PROACTIVELY" in descriptions ✅ WHAT + WHEN descriptions: Both capability and triggers ✅ Test first: Build 3+ evaluations before extensive documentation ✅ Least privilege: Limit tools to necessary set

✅ 500行规则：SKILL.md和Agent提示词不超过500行 ✅ 渐进式披露：使用参考文件存放详细内容 ✅ 主动式语言：描述中包含"主动调用（use PROACTIVELY）" ✅ WHAT + WHEN描述：同时包含能力和触发场景 ✅ 先测试后开发：编写大量文档前先完成3+个测试用例 ✅ 最小权限原则：仅授予必要的工具权限

Anti-Patterns

反模式

❌ Vague descriptions without triggers ❌ Over 500 lines without references ❌ Second-person voice ("you should...") ❌ All tools when subset suffices ❌ No examples in agent descriptions

❌ 模糊描述，缺少触发场景 ❌ 超过500行却未使用参考文件 ❌ 第二人称表述（"你应该..."） ❌ 授予全部工具权限，而不是必要子集 ❌ Agent描述中没有示例

Quick Reference

速查参考

Agent Model Selection:

Haiku: Fast, simple tasks (< 3s)
Sonnet: Balanced, most use cases (< 10s)
Opus: Complex reasoning (< 30s)
Inherit: Match main conversation

File Locations:

Agents:
```
.claude/agents/*.md
```
Skills:
```
.claude/skills/{name}/SKILL.md
```
Output Styles:
```
.claude/output-styles/*.md
```

Management Commands:

```
/agents
```
- Interactive agent management
```
/output-style
```
- Switch output styles

Status: Production Ready | Lines: ~200 | Progressive Disclosure: ✅

Agent模型选择：

Haiku：快速、简单任务（<3秒）
Sonnet：平衡型，大多数场景（<10秒）
Opus：复杂推理（<30秒）
Inherit：匹配主对话模型

文件位置：

Agent：
```
.claude/agents/*.md
```
Skill：
```
.claude/skills/{name}/SKILL.md
```
输出样式：
```
.claude/output-styles/*.md
```

管理命令：

```
/agents
```
- 交互式Agent管理
```
/output-style
```
- 切换输出样式

状态：生产就绪 | 行数：~200 | 渐进式披露：✅

claude-extensibility

Original

Translation

Claude Code Extensibility

Claude Code 扩展性

Related Skills

相关技能

Core Principles

核心原则

Extension Types

扩展类型

Agent Development

Agent开发

Quick Start: Agent

Agent快速入门

Agent Name

Agent名称

Core Strategy

核心策略

1. Phase Name

1. 阶段名称

YAML Fields

YAML字段说明

Model Selection

模型选择

Built-in Subagents

内置子Agent

Agent Locations

Agent存储位置

CLI-Defined Agents

CLI定义的Agent

Resumable Agents

可恢复Agent

Skill Development

Skill开发

Quick Start: Skill

Skill快速入门

Skill Name

Skill名称

Purpose

用途

When to Use

适用场景

Key Information

关键信息

YAML Fields

YAML字段说明

Description Format (WHAT + WHEN)

描述格式（WHAT + WHEN）

Tool Access Control

工具权限控制

Skill Locations

Skill存储位置

Skill Structure

Skill目录结构

Output Styles

输出样式

Quick Start: Output Style

输出样式快速入门

Custom Style Instructions

自定义样式说明

Specific Behaviors

具体行为

YAML Fields

YAML字段说明

Built-in Styles

内置样式

Output Style Locations

输出样式存储位置

Usage

使用方法

Testing

测试

Key Question: Does it activate when expected?

核心问题：是否在预期场景下激活？

Common Workflows

常见工作流

Create Agent

创建Agent

Create Skill