Claude Code Skills 进阶

⏱️ 15分钟

Claude Code 进阶：用 Skills 重构 AI 工作流

作为一名重度 Claude Code 用户，我相信大家都有过这种既视感：每次开一个新项目，Claude 就像个刚入职的实习生，一脸懵懂。

你得一遍遍告诉它：我们用的是这种 Coding Style、部署流程是这样的、API 鉴权要走这个逻辑……讲一次还好，讲十次真的心态崩。

之前的解决方案通常是 CLAUDE.md。把规则写进去，启动即加载。但随着项目变大，这个文件越来越臃肿。我之前遇到过因为 CLAUDE.md 塞了太多 Prompt，导致 Claude 启动变慢，甚至因为它预加载了所有内容，不仅浪费了宝贵的 Context Window，还导致模型注意力分散，回答质量下降。

最近 Anthropic 推出的 Skills 功能，终于优雅地解决了这个问题。这不仅仅是一个功能，而是一种更符合工程直觉的 AI 知识模块化架构。

核心架构：Progressive Disclosure

这可能是 Skills 设计最性感的地方。

以前的 CLAUDE.md 是全量加载，不管你问什么，所有规则一股脑塞进 Context。而 Skills 采用了一种分层加载机制，官方称之为 Progressive Disclosure。

根据观察和官方文档，它其实把 Context 分成了三层：

L1 Metadata (元数据层)

启动时只加载 Skills 的 name 和 description。这层非常轻量（约 100 tokens）。Claude 仅凭这层信息来路由：这个问题需不需要调用某个 Skill？

L2 Instructions (指令层)

当 Claude 判定命中某个 Skill 后，才会加载该 Skill 下 SKILL.md 的主体内容（建议控制在 5000 tokens 以内）。

L3 Resources (资源层)

如果 SKILL.md 引用了脚本或参考文档，这些文件是 On-Demand (按需) 读取的。

架构优势

这种架构意味着：理论上你可以给 Claude 挂载无限的知识库，只要你的 Description 写得够准，它就只在需要的时候调取记忆，完全不占闲置 Context。这对于对 Token 效率有洁癖的开发者来说，简直是福音。

实战：手搓一个 Skill 的工程结构

一个标准的 Skill 其实就是一个独立的目录包。结构非常像我们在写 Node.js 模块或者 Ansible Role。

目录结构

my-skill/
├── SKILL.md          # 核心入口（必须）
├── scripts/          # Python 或 Bash 脚本（可选）
├── references/       # 文档规范（可选）
└── assets/           # 静态资源模板（可选）

你需要创建一个文件夹（例如 my-skill），在这个文件夹下必须包含一个 SKILL.md 文件作为核心入口。此外，你还可以根据需要创建 scripts 目录存放 Python 或 Bash 脚本，references 目录存放文档规范，以及 assets 目录存放静态资源模板。

SKILL.md 的 Frontmatter 配置

这里有严格的格式要求，踩坑经验分享：

---
name: my-skill
description: 当用户要求提交代码时，使用此 Skill 进行代码规范检查和提交流程
allowed-tools: Read, Glob, Bash, Grep, Write
---
# Skill 标题

这里是 Skill 的主体内容...

注意事项：

name 字段：只能包含小写字母、数字和连字符，并且必须与目录名称完全一致
description 字段：这是写给 LLM 的 Router 看的，你得明确描述 Trigger Condition (触发条件)，比如"当用户要求提交代码时……"，这样 Claude 才能精准命中

Skills, MCP, Custom Commands 怎么选？

这是最容易混淆的部分。既然都有 MCP (Model Context Protocol) 了，为啥还要 Skills？以下是理解模型：

类型	本质	适用场景	触发方式	定位
Custom Commands	宏 (Macro) / 静态 Prompt	明确知道现在要干嘛，如 Lint 检查、代码重构	手动触发	手动挡工具
MCP	IO 接口 / 手脚	连接外部世界，如读数据库、调 GitHub API	按需调用	AI 的感官和肢体
Skills	程序性知识 / 脑回路	复杂思维链或工作流，如符合团队规范的 Code Review	AI 自动决策	AI 的专业技能包

互补关系

不要觉得 Skills 会取代 MCP。它们是互补的。

举个例子：你写了一个 Deploy Skill (大脑)，告诉 Claude 部署流程分几步；而在执行过程中，Claude 会调用 AWS MCP (手脚) 去实际操作服务器。

Skills (大脑：知道怎么做)
    ↓
    调用
    ↓
MCP (手脚：实际执行)

6 个实用 Skills 示例

以下是来自 feiskyer/claude-code-settings 的 6 个实用 Skills，可以直接安装使用。

1. codex-skill - Codex CLI 自动化

将任务交给 OpenAI Codex 执行，适合需要使用 GPT-5 系列模型的场景。

安装：

/plugin marketplace add feiskyer/claude-code-settings
/plugin install codex-skill

核心功能：

多种执行模式（只读、工作区写入、完全访问）
模型选择（gpt-5, gpt-5.1, gpt-5.1-codex）
无需审批的自主执行
JSON 输出支持
可恢复的会话

前置要求： Codex CLI (npm i -g @openai/codex 或 brew install codex)

2. autonomous-skill - 长时任务自动化

执行跨多个会话的复杂长时任务，使用双代理模式（Initializer + Executor）。

安装：

/plugin install autonomous-skill

核心功能：

双代理模式（Initializer 创建任务列表，Executor 完成任务）
跨会话自动继续，带进度跟踪
任务隔离，每个任务有独立目录 (.autonomous/<task-name>/)
通过 task_list.md 和 progress.md 持久化进度

使用示例：

You: "Please use autonomous skill to build a REST API for a todo app"
Claude: [创建 .autonomous/build-rest-api-todo/，初始化任务列表，开始执行]

3. nanobanana-skill - Gemini 图像生成

使用 Google Gemini API 生成或编辑图像。

安装：

/plugin install nanobanana-skill

核心功能：

多种宽高比（正方形、竖屏、横屏、超宽）
图像编辑能力
多种分辨率（1K、2K、4K）
支持 gemini-3-pro-image-preview, gemini-2.5-flash-image

前置要求：

在 ~/.nanobanana.env 配置 GEMINI_API_KEY
Python3 + google-genai, Pillow, python-dotenv

4. youtube-transcribe-skill - YouTube 字幕提取

从 YouTube 视频链接提取字幕/转录文本。

安装：

/plugin install youtube-transcribe-skill

核心功能：

双重提取方式：CLI（快速）和浏览器自动化（备用）
自动选择字幕语言（zh-Hans, zh-Hant, en）
高效的 DOM 提取方式
保存转录到本地文本文件

前置要求： yt-dlp（CLI 方式）或 chrome-devtools-mcp（浏览器方式）

5. kiro-skill - 交互式功能开发

从想法到实现的交互式功能开发工作流。

安装：

/plugin install kiro-skill

触发条件： 提到 "kiro" 或引用 .kiro/specs/ 目录

工作流程：

Requirements → 定义需要构建什么（EARS 格式 + 用户故事）
Design → 确定如何构建（架构、组件、数据模型）
Tasks → 创建可执行的实施步骤（测试驱动、增量式）
Execute → 逐一实现任务

使用示例：

You: "I need to create a kiro feature spec for user authentication"
Claude: [自动使用 kiro-skill]

6. spec-kit-skill - 规范驱动开发

GitHub Spec-Kit 集成，用于基于规范的开发。

安装：

/plugin install spec-kit-skill

触发条件： 提到 "spec-kit"、"speckit"、"constitution"、"specify" 或引用 .specify/ 目录

前置安装：

# 安装 spec-kit CLI
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 初始化项目
specify init . --ai claude

7 阶段工作流：

Constitution → 建立治理原则
Specify → 定义功能需求
Clarify → 解决歧义（最多 5 个问题）
Plan → 创建技术策略
Tasks → 生成依赖排序的任务
Analyze → 验证一致性（只读）
Implement → 执行实施

实战经验总结

目前的 Claude Code 就像一个通用型人才，什么都懂一点但都不精。Skills 的本质，就是让我们把领域专家的 Know-how 封装成一个个 Docker 容器般的独立包。

Skill 类型	示例
代码规范	PR Review 标准、Commit 规范
测试流程	单元测试规范、E2E 测试流程
部署流程	CI/CD 配置、环境部署
特定库使用	React 组件规范、NestJS 模块规范
业务逻辑	支付流程、用户认证流程

最佳实践

Description 要精准：这是 Skill 能否被正确触发的关键
内容控制在 5000 tokens 内：太长会影响加载效率
按领域拆分：一个 Skill 只负责一个领域
引用外部资源：复杂内容放到 references/ 或 scripts/

总结

Skills 是 Claude Code 的一次重要升级，它解决了 CLAUDE.md 臃肿、Context 浪费的问题，让我们可以：

模块化管理 AI 知识
按需加载 减少 Token 浪费
精准触发 提高回答质量

如果你还在用一个巨大的 CLAUDE.md，是时候考虑迁移到 Skills 架构了！

原文作者：AI 观测室 | 发布于 2026-01-10

Claude Code Skills 进阶

Claude Code 进阶：用 Skills 重构 AI 工作流

核心架构：Progressive Disclosure

L1 Metadata (元数据层)

L2 Instructions (指令层)

L3 Resources (资源层)

架构优势

实战：手搓一个 Skill 的工程结构

目录结构

SKILL.md 的 Frontmatter 配置

Skills, MCP, Custom Commands 怎么选？

互补关系

6 个实用 Skills 示例

1. codex-skill - Codex CLI 自动化

2. autonomous-skill - 长时任务自动化

3. nanobanana-skill - Gemini 图像生成

4. youtube-transcribe-skill - YouTube 字幕提取

5. kiro-skill - 交互式功能开发

6. spec-kit-skill - 规范驱动开发

实战经验总结

推荐的 Skills 拆分方式

最佳实践

总结

📚 相关资源