打造属于你的数字工匠工具箱

一、每个开发者都需要一个工坊

好的工匠都有自己的工坊——工具挂在顺手的位置，技艺烂熟于心，需要材料时有可靠的供应商。

Claude Code 不只是一个"AI 助手"，它是你的数字工坊。你可以布置自己的工具（Commands）、培养技艺（Skills）、请来助手（Agents）、连接供应商（MCP）。

本文将带你了解如何打造适合自己的 Claude Code 工坊。

二、Commands：挂在墙上的专用工具

Commands 就像工匠墙上的刨子、凿子——你知道它在那里，需要时随手可取。

什么是 Commands

Commands 属于手动激活的自定义指令集合。其核心逻辑是将高频复用的 Prompt 固化为 Markdown 格式，借由 /指令名称 实现一键唤出。

存放位置

• 项目命令：.claude/commands/ —— 可通过 Git 与团队共享
• 个人命令：~/.claude/commands/ —— 在所有项目中可用

文件格式

---
allowed-tools: Bash(git:*), Read, Grep
argument-hint: [文件路径] [关注度]
description: 分析代码性能瓶颈
model: claude-sonnet-4-20250514
---

请分析当前代码中的性能问题。
重点检查：
1. 冗余计算模式
2. 内存泄漏风险
3. 低效循环结构

文件：$1
关注度：$2

如果发现优化空间，请提供具体的改进方案。

Frontmatter 配置字段

参数语法

命名空间

借助子目录层级对命令进行分类管理：

• .claude/commands/frontend/deploy.md → /deploy (project:frontend)
• .claude/commands/backend/migrate.md → /migrate (project:backend)

Commands 如同悬挂于工坊墙面的凿具与刨具——位置固定了然于胸，用时探手即得。

三、Agents：你的学徒与助手

Agents 犹如工坊中受训的学徒工——分派具体差事后独立作业，完结后回禀成果。

什么是 Agents

Agents 具备隔离的会话环境、定制化的行为指令以及限定的操作范围。它们自主承接专项事务，处理完毕后向主会话汇总成果。

与 Skill 的区别

• Skill 是"教会 Claude 新知识"
• Agent 是"派出另一个 Claude 去干活"

存放位置

• 项目代理：.claude/agents/agent-name.md
• 个人代理：~/.claude/agents/agent-name.md
• 插件代理：插件目录下的 agents/agent-name.md

完整示例

---
name: arch-reviewer
description: 系统架构评审专家。在模块设计或重构后自动进行架构合理性、接口一致性和依赖清晰度审查。
tools: Read, Grep, Glob
model: sonnet
permissionMode: default
skills: arch-design
---

# 系统提示词

你是一位系统架构评审专家，负责确保模块设计的合理性和一致性。

当被调用时：
1. 运行 `git diff` 查看最近的变更
2. 聚焦于修改的接口和模块
3. 立即开始评审

评审清单：
- 模块划分合理
- 接口设计一致
- 依赖关系清晰
- 扩展性考量充分
- 无循环依赖
- 遵循项目架构规范

配置字段详解

核心优势

• 上下文隔离：子代理的中间步骤不会污染主对话
• 专业聚焦：通过专属系统提示词让代理更专注于特定任务
• 工具限制：可限制代理只能使用特定工具，提高安全性

内置子代理

Agents 将 Claude Code 从"单机设备"升级为"协作班组"——你能够统筹多位专员并行作业，自身则始终锚定在关键决策环节。

四、Skills：内化的手艺与肌肉记忆

Skills 恰似匠人经年累月形成的身体记忆——无需刻意思索，本能般自然流露。

什么是 Skills

Skills 属于条件感应的能力增强模块，向 Claude 传授特定领域的处理方法。系统依据语义关联度自主识别并加载适用技能，免除人工显式指定的步骤。

与 Command 的区别

• Command 是主动技能（按下按钮）
• Skill 是被动技能（条件触发）

存放位置

• 项目技能：.claude/skills/技能名/SKILL.md
• 个人技能：~/.claude/skills/技能名/SKILL.md
• 插件技能：插件目录下的 skills/技能名/SKILL.md

目录结构示例

.claude/skills/tech-writing/
├── SKILL.md              # 核心技能文件（必需）
├── reference.md          # 详细 API 文档
├── examples.md           # 使用示例
└── scripts/
    └── diagram.py        # 辅助脚本

完整 SKILL.md 示例

---
name: tech-writing
description: 撰写技术设计文档。当需要产出架构说明、接口定义，或用户询问"如何记录这个设计"时使用。
allowed-tools: Read, Grep, Glob
model: claude-opus-4-20250514
---

# 技术文档撰写技能

撰写技术文档时，请始终遵循以下步骤：

1. **梳理背景诉求**：说明设计要解决的问题和上下文
2. **绘制系统架构**：使用 ASCII 艺术绘制模块关系图
3. **描述数据流向**：一步步说明请求的处理过程
4. **标注决策考量**：记录关键设计选择和取舍理由

## 额外资源

- 完整 API 详情参阅 [reference.md](reference.md)
- 使用示例参阅 [examples.md](examples.md)

## 辅助脚本

生成架构图：
```bash
python scripts/diagram.py design.md

### 元数据字段

| 字段 | 必需 | 说明 |
|------|------|------|
| `name` | 是 | 技能代号（限小写与连字符，长度上限 64 字符） |
| `description` | 是 | 阐释技能用途与触发条件（上限 1024 字符），供系统进行语义关联判断 |
| `allowed-tools` | 否 | 被授予免确认直接调用权限的工具集 |
| `model` | 否 | 限定该技能执行时所调用的具体模型 |

### 渐进式披露模式

最佳实践：主 `SKILL.md` 文件保持在 500 行以内，详细内容放在关联文件中。

```markdown
## 概述
[核心指令]

## 额外资源
- 完整 API 详情参阅 [reference.md](reference.md)
- 使用示例参阅 [examples.md](examples.md)

## 辅助脚本
运行验证：
```bash
python scripts/validate.py input.txt

### 技能工作流程

1. **发现**：Claude 启动时加载所有技能的名称和描述
2. **激活**：当用户请求与某技能描述匹配时，Claude 请求使用该技能
3. **执行**：Claude 读取完整的 SKILL.md 内容并按指令执行

Skills 让 Claude 学会了"读空气"——它开始理解你话语背后的真实需求。

---

## 五、MCP：外部材料与支援网络

MCP 好比工坊的物资供应渠道——无论何种原料需求，皆能按需调配。

### 什么是 MCP

MCP（Model Context Protocol）作为**统一对接规范**，使 Claude 得以桥接外部服务生态。它突破 Claude 原生能力疆域，打通与外围系统（检索引擎、数据存储、文件管理）的数据通道。

### MCP 与 Skill/Agent 的区别

- **Skill/Agent** 是 Claude 的"内在能力"
- **MCP** 是"外部连接"，调用外部服务

### 配置位置

- **项目级**：`.mcp.json`
- **用户级**：`~/.mcp.json`（跨项目可用）

### 示例配置

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"],
      "env": {}
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "./data.db"],
      "env": {}
    }
  }
}

MCP 配置示例

实际应用

• 需要文件操作？接入 Filesystem MCP
• 需要数据查询？接入 SQLite MCP
• 需要版本管理？接入 Git MCP

MCP 让工坊不再是封闭的。你可以连接无限的外部资源，能力边界被大大扩展。

六、Plugin：成套的工具箱

Plugins 宛若规格统一的工具套装——支持整体收纳、流转与多次启用。

什么是 Plugins

Plugin 充当着 Commands、Agents、Skills、Hooks 及 MCP 配置的集合封装载体，用于整体交付与复用。

本质：Plugin 不是功能本身，是包装器。

目录结构

my-plugin/
├── .claude-plugin/
│   └── plugin.json      # 必需 - 插件清单
├── commands/            # 可选 - 斜杠命令
│   └── hello.md
├── agents/              # 可选 - 子代理
│   └── arch-reviewer.md
├── skills/              # 可选 - 技能
│   └── tech-writing/
│       └── SKILL.md
├── hooks/               # 可选 - 钩子
│   └── hooks.json
├── .mcp.json            # 可选 - MCP 服务器配置
├── .lsp.json            # 可选 - LSP 服务器配置
├── README.md
└── LICENSE

插件清单 (plugin.json)

{
  "name": "team-dev-toolkit",
  "description": "团队开发规范检查与格式化工具集",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "homepage": "https://github.com/user/team-dev-toolkit",
  "repository": "https://github.com/user/team-dev-toolkit",
  "license": "MIT"
}

清单字段

插件组件详解

Commands（命令）：

• 放在 commands/ 目录
• 自动添加命名空间：commands/hello.md → /my-plugin:hello

Agents（代理）：

• 放在 agents/ 目录
• 格式与独立代理文件相同

Skills（技能）：

• 放在 skills/ 目录
• 每个技能一个文件夹，包含 SKILL.md

Hooks（钩子）：

• 放在 hooks/hooks.json
• 定义事件处理器

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "npm run lint:fix $FILE"}]
      }
    ]
  }
}

MCP 服务器：

• 放在 .mcp.json
• 与独立 MCP 配置格式相同

LSP 服务器：

• 放在 .lsp.json
• 定义语言服务器配置

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

开发与测试

本地测试：

claude --plugin-dir ./my-plugin

测试多个插件：

claude --plugin-dir ./plugin-one --plugin-dir ./plugin-two

从现有配置创建插件：

mkdir my-plugin
mkdir my-plugin/.claude-plugin
cp -r .claude/commands my-plugin/
cp -r .claude/agents my-plugin/
cp -r .claude/skills my-plugin/

分发方式

1. 添加 README.md 说明安装和使用方法
2. 使用语义版本号管理版本
3. 发布到插件市场
4. 用户通过 /plugin install plugin-name@marketplace-name 安装

Plugin 让个人经验变成了团队资产。好的工坊，值得被复制。

七、如何选择：决策指南

好的工匠知道什么活用什么工具。以下是选择决策树：

遇到任务 ↓
├─ 明确知道要做什么？
│  └─ 是 → Command（显式调用）
│  └─ 否 → 继续
├─ 任务复杂，可能污染对话？
│  └─ 是 → Agent（独立上下文）
│  └─ 否 → 继续
├─ 希望自动识别处理？
│  └─ 是 → Skill（语义触发）
│
└─ 需要外部数据/工具？
   └─ 是 → MCP（外部连接）

选择对比表

八、打造属于你的工坊

总结

Claude Code 的价值核心，并非源于其原生智能水平，而在于赋予使用者构建个性化作业管线的权限。

自触手可及的器具（Commands），到身体记忆般的技艺（Skills），再至可托付的协作人（Agents）与无边界的原料库（MCP）——这套体系支持持续迭代与进化。

现在，开始布置你的工坊吧。