claude-extensibility

Claude Code 扩展

按照 Anthropic 最佳实践，对 Agent、技能和输出风格执行 CRUD 操作。

相关技能

重要： 创建或编辑提示词时，请使用 prompt-enhancer 技能来提升质量。

Skill("prompt-enhancer")  → Enhance skill/agent prompt content

核心原则

• 简洁：直接调用工具，避免复杂抽象
• 聚焦：每个扩展只承担一项明确职责
• 精炼：目标少于 500 行，采用渐进式披露
• 高效：优化令牌用量和响应时间

扩展类型

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

Agent 开发

参考： references/agent-development.md — 完整的 YAML 结构、模型和工具选择、系统提示词模式及优化技巧。

快速入门：Agent

---
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
---

# Agent Name

Brief mission statement.

## Core Strategy

### 1. Phase Name
Approach and techniques

<format>
Expected output structure
</format>

YAML 字段

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

模型选择

模型	适用场景	目标耗时
haiku	快速任务、探索、搜索	< 3s
sonnet	均衡表现，适用于大多数场景	< 10s
opus	复杂推理、架构设计	< 30s
inherit	与主对话使用相同的模型	不定

内置子 Agent

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

Agent 位置

位置	范围	优先级
.claude/agents/	项目	最高
~/.claude/agents/	用户（所有项目）	较低
插件 agents/	特定插件	不定
--agents CLI 标志	仅当前会话	中

CLI 定义的 Agent

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"
  }
}'

可恢复的 Agent

继续之前的对话：

• 每次执行都会获得唯一的 agentId
• 对话记录存储在 agent-{agentId}.jsonl 中
• 使用之前的 agentId 恢复，以完整上下文继续对话

技能开发

参考： references/skill-development.md — 完整结构、触发模式和钩子系统。

快速入门：技能

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

# Skill Name

## Purpose
What this skill helps with

## When to Use
Specific scenarios and conditions

## Key Information
Guidance, patterns, examples

YAML 字段

字段	必填	描述
name	是	小写，使用连字符，最多 64 个字符
description	是	WHAT + WHEN 格式，最多 1024 个字符，需加引号
allowed-tools	否	限制工具访问权限（安全性）

描述格式（WHAT + WHEN）

结构：

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

好的示例：

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."

不好的示例：

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

工具访问控制

使用 allowed-tools 限制 Claude 可用的工具：

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

技能位置

位置	范围
.claude/skills/{name}/SKILL.md	项目（通过 git 共享）
~/.claude/skills/{name}/SKILL.md	用户（所有项目）
插件 skills/	随插件打包

技能结构

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

输出风格

修改 Claude Code 主 Agent 的行为。

快速入门：输出风格

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

# Custom Style Instructions

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

## Specific Behaviors
[Define assistant behavior...]

YAML 字段

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

内置样式

• Default：标准软件工程
• Explanatory：在任务之间提供教育性见解
• Learning：通过 TODO(human) 标记进行协作

输出样式位置

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

用法

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

测试

核心问题：它会在预期时激活吗？

Agent 测试：

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

技能测试：

• 测试应该触发的提示词
• 测试不应该触发的提示词
• 使用以下命令调试：claude --debug

常见工作流

创建 Agent

1. 创建 .claude/agents/{name}.md
2. 编写 YAML frontmatter（name、description、tools、model）
3. 编写系统提示词（少于 500 行）
4. 使用 Task 工具进行测试
5. 根据性能进行优化

创建技能

1. 创建 .claude/skills/{name}/SKILL.md
2. 编写包含 WHAT + WHEN 描述的 YAML frontmatter
3. 编写内容（少于 500 行）
4. 使用 Skill("prompt-enhancer") 改进提示词
5. 为详细内容添加参考文件
6. 测试：它会在预期时激活吗？

优化扩展

1. 测量基准数据（行数、令牌用量、响应时间）
2. 将详细内容移至参考文件
3. 使用 Skill("prompt-enhancer") 改进提示词
4. 去掉第二人称表达
5. 使用代码块替代散文
6. 添加 XML 结构
7. 测试并验证改进效果

最佳实践

Anthropic 指南

✅ 500 行规则：将 SKILL.md 和 Agent 提示词控制在 500 行以内
✅ 渐进式披露：使用参考文件存放详细内容
✅ 主动式措辞：在描述中加入 “use PROACTIVELY”
✅ WHAT + WHEN 描述：同时说明能力和触发条件
✅ 先测试：在编写大量文档前，先构建 3 项以上评估
✅ 最小权限：将工具限制在必要范围内

反模式

❌ 描述含糊，没有触发条件
❌ 超过 500 行且没有参考文件
❌ 使用第二人称表达（“you should...”）
❌ 明明只需部分工具，却使用全部工具
❌ Agent 描述中没有示例

快速参考

Agent 模型选择：

• Haiku：快速、简单的任务（少于 3 秒）
• Sonnet：均衡，适用于大多数场景（少于 10 秒）
• Opus：复杂推理（少于 30 秒）
• Inherit：与主对话保持一致

文件位置：

• Agents：.claude/agents/*.md
• Skills：.claude/skills/{name}/SKILL.md
• 输出样式：.claude/output-styles/*.md

管理命令：

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

---

状态：可用于生产环境 | 行数：约 200 | 渐进式披露：✅