Claude on Tao

MCP vs Skill：AI 能力扩展的两种范式与决策指南

di4urp@gmail.com (taevas) — Tue, 17 Mar 2026 13:47:37 +0800

核心概念

在构建 AI 应用的能力扩展时，我们面临两个主要选择：

MCP（Model Context Protocol）：连接层协议，解决 AI 与外部系统/工具的标准化通信问题
Skill：认知层封装，解决任务流程与知识复用问题

简单来说，MCP 回答"能不能访问、怎么连、谁能连、怎么管“的问题，而 Skill 回答”怎么做、流程是什么、输出要什么格式“的问题。

架构对比

┌─────────────────────────────────────────────────────────────────┐
│ AI 客户端 (Claude/Cursor 等) │
├─────────────────────────┬───────────────────────────────────────┤
│ │ │
│ Skill 层 (认知) │ MCP 层 (连接) │
│ │ │
│ ┌─────────────────────┐│ ┌─────────────────────────────┐ │
│ │ 任务流程编排 ││ │ 统一工具接口 │ │
│ │ 知识模板应用 ││ │ 标准化通信协议 │ │
│ │ 提示词工程 ││ │ 跨平台兼容 │ │
│ └─────────────────────┘│ └─────────────────────────────┘ │
│ │ │
└─────────────────────────┴───────────────────────────────────────┘
│
▼
┌─────────────────┐
│ 外部系统/资源 │
│ (DB/API/文件) │
└─────────────────┘

特征对比表

维度	MCP	Skill
定位	连接层协议	认知层封装
适用范围	跨平台、跨模型	特定平台内
主要解决	标准化通信、权限管控	任务流程、知识复用
部署位置	独立 Server进程	客户端/平台内
权限能力	系统级、本地访问	通常受限
标准程度	开放协议、强约束	自由定义、弱约束
生态性	可插拔、可扩展	封闭/半封闭

MCP 不可替代的六类场景

一、跨平台 / 跨模型 / 跨客户端统一接入

问题场景：同一套工具/服务需要被多个不同 AI 客户端调用。

典型用例：

场景	说明	Skill 的局限性
多客户端共享	Claude、Cursor、VS Code Copilot、自定义 Agent 都要调用同一套后端	Skill 仅绑定到特定平台
跨模型复用	Anthropic、OpenAI、字节等模型都要调用同一套后端能力	Skill 模型绑定性强
企业内协作	多团队、多 Agent 平台共享一套外部能力（DB、API、文件系统）	Skill 难以统一分发
开放生态	让第三方 AI 接入你的服务	Skill 是私有实现

MCP 解决方案示例：

# mcp_server.py
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

mcp = Server("database-access")

@mcp.list_tools()
async def list_tools() -> list[Tool]:
 return [
 Tool(
 name="query_database",
 description="Execute SQL queries on the main database",
 inputSchema={
 "type": "object",
 "properties": {
 "sql": {"type": "string", "description": "SQL query"}
 },
 "required": ["sql"]
 }
 )
 ]

@mcp.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
 if name == "query_database":
 # 任何 MCP 客户端都可以调用这个功能
 result = execute_sql(arguments["sql"])
 return [TextContent(type="text", text=str(result))]

async def main():
 async with stdio_server() as (read_stream, write_stream):
 await mcp.run(read_stream, write_stream)

二、本地 / 私有环境深度访问

问题场景：需要直接访问本地资源或敏感数据不出域。

典型用例：

场景	说明	Skill 的局限性
本地文件系统	直接读写本地代码库、配置文件	Skill 通常无本地写权限
本地数据库	直接连线本地 MySQL/PostgreSQL	Skill 多为云端调用
内网服务	访问企业内网、私有云、本地服务器	Skill 跨内网困难
数据合规	敏感数据本地处理、不流出	Skill 难保证数据不出域

MCP 深度访问示例：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import * as fs from "fs/promises";
import * as path from "path";

const server = new Server({
 name: "local-dev-tools",
 version: "1.0.0"
});

// 本地代码库分析
server.setRequestHandler(CallToolRequestSchema, async (request) => {
 if (request.params.name === "analyze-codebase") {
 const projectPath = request.params.arguments.path;

 // 直接访问本地文件系统
 const files = await fs.readdir(projectPath, { recursive: true });
 const codeFiles = files.filter(f => f.endsWith('.ts') || f.endsWith('.py'));

 // 并发读取文件内容（Skill 做不到这么高效）
 const contents = await Promise.all(
 codeFiles.map(f => fs.readFile(path.join(projectPath, f), 'utf-8'))
 );

 return {
 content: [{
 type: "text",
 text: JSON.stringify({ files: codeFiles, totalSize: contents.join('').length })
 }]
 };
 }
});

三、集中式安全、权限与审计治理

问题场景：企业级应用需要统一的安全管控入口。

典型用例：

治理维度	MCP 能力	Skill 的局限性
密钥管理	统一 API 密钥存储、轮换	密钥分散在各 Skill 中
权限分级	基于用户的精细化权限控制	Skill 难以全局鉴权
�审计	统一日志、调用追溯、速率限制	日志分散、难以聚合
合规要求	必须通过统一网关管控所有调用	调用路径不透明
多租户隔离	租户级别的数据隔离	Skill 难以实现租户隔离

MCP 权限治理架构：

class AuthMiddleware:
 """MCP 服务端的统一权限网关"""

 async def __call__(self, request: ToolRequest) -> ToolResponse:
 # 1. 验证用户身份
 user = await self.authenticate(request.headers)

 # 2. 检查工具调用权限
 if not await self.check_permission(user, request.tool_name):
 raise PermissionDenied(f"User {user.id} cannot access {request.tool_name}")

 # 3. 速率限制
 if not await self.check_rate_limit(user):
 raise RateLimitExceeded("Too many requests")

 # 4. 执行并审计
 start_time = time.time()
 try:
 response = await self.execute_tool(request)
 await self.audit_log(user, request, response, duration=time.time() - start_time)
 return response
 except Exception as e:
 await self.audit_error(user, request, e)
 raise

四、复杂系统 / 多数据源的插拔式集成

问题场景：需要接入大量异构系统，实现动态发现和挂载。

典型用例：

系统类型	MCP 优势	Skill 的局限
数据库集群	动态发现表结构、执行查询	Skill 需硬编码每个 DB
知识库	统一检索接口，可插拔后端	Skill 难以扩展
工单系统	统一的 CRUD 接口适配多系统	需为每个系统写 Skill
IM 通道	统一消息发送接口	Skill 通道绑定固定
第三方 SaaS	Slack、Notion、Jira 统一封装	各需要独立 Skill

MCP 动态资源发现示例：

@mcp.list_resources()
async def list_resources() -> list[Resource]:
 """动态发现所有可用的数据源"""
 resources = []

 # 数据库资源动态发现
 for db_config in await discover_databases():
 for table in await list_tables(db_config):
 resources.append(Resource(
 uri=f"db://{db_config.name}/{table}",
 name=f"{db_config.name}.{table}",
 description=f"Table {table} in {db_config.name}",
 mimeType="application/json"
 ))

 # 文件系统资源
 for root, dirs, files in os.walk("/shared/documents"):
 for file in files:
 resources.append(Resource(
 uri=f"file://{os.path.join(root, file)}",
 name=file,
 description=f"Document file",
 mimeType="text/plain"
 ))

 return resources

# AI 可以自主探索和调用这些资源
@mcp.read_resource()
async def read_resource(uri: str) -> str:
 if uri.startswith("db://"):
 return await query_table(uri)
 elif uri.startswith("file://"):
 return await read_file(uri)

五、真实操作与系统级自动化

问题场景：需要执行真实的写操作和跨系统业务流程。

典型用例：

操作类型	MCP 能力	Skill 的局限
写操作	创建工单、发送消息、更新 CRM	Skill 多为模拟/只读
SQL 执行	执行 INSERT/UPDATE/DELETE	Skill 难以执行写 SQL
代码提交	Git commit/pull request 操作	Skill 通常无 Git 写权限
配置修改	修改系统配置、环境变量	Skill 系统权限受限
跨服务流程	跨网络的业务流程编排	Skill 流程编排能力弱
运维操作	实时监控、告警处理	Skill 稳定性难以保证

MCP 自动化工作流示例：

@mcp.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
 if name == "onboard_new_user":
 """跨系统自动化：新用户入职流程"""

 # 1. 在 HR 系统创建员工记录
 employee_id = await hr_api.create_employee(arguments)

 # 2. 在 AD 域创建账号
 ad_user = await ad_api.create_user({
 "username": arguments["email"].split("@")[0],
 "email": arguments["email"],
 "department": arguments["department"]
 })

 # 3. 在 Jira 创建工单分配设备
 ticket_id = await jira_api.create_ticket({
 "summary": f"设备申请: {arguments['name']}",
 "assignee": "it-support"
 })

 # 4. 在 Slack 发送欢迎消息
 await slack_api.send_message(
 channel="#announcements",
 text=f"欢迎新同事 {arguments['name']} 加入 {arguments['department']}！"
 )

 return [TextContent(type="text", text=f"""
 入职流程完成：
 - 员工ID: {employee_id}
 - AD账号: {ad_user.username}
 - 设备工单: {ticket_id}
 """)]

六、协议级标准化与生态兼容

问题场景：需要构建可插拔、可扩展的 AI 工具生态。

标准化维度	MCP	Skill
协议规范	强制 JSON-RPC 2.0 接口	自定义，无强制标准
接口约束	Schema 验证、类型检查	自由度极高
版本兼容	明确的版本管理	难以保证向后兼容
互操作性	不同 MCP Server 可互换	Skill 难以替换
生态扩展	第三方可贡献 Server	生态封闭

MCP 标准化带来的生态价值：

// 任何符合 MCP 标准的 Server 都可以被任何 MCP Client 使用
interface MCPTool {
 name: string;
 description: string;
 inputSchema: {
 type: "object";
 properties: Record<string, { type: string; description: string }>;
 required: string[];
 };
}

// 客户端可以动态加载任何 MCP Server
async function loadMCPServer(serverPath: string) {
 const server = spawn(serverPath);
 return new MCPClient(server.stdin, server.stdout);
}

// 生态示例：插件式架构
const pluginRegistry = {
 "filesystem": "/opt/mcp-servers/fileserver",
 "database": "/opt/mcp-servers/dbconnector",
 "cloud-storage": "/opt/mcp-servers/s3-connector"
};

// 用户可以随意替换某个插件，无需修改客户端代码

Skill 的优势场景

虽然 MCP 在上述场景不可替代，但 Skill 在以下领域更有优势：

1. 轻量级任务流程编排

适用场景：固定模式的任务流程，不需要外部系统访问。

# SKILL.md 中的工作流定义
---
name: code-review
description: "Perform code review with standard checklist"
---

## Workflow

1. Read the code file provided by user
2. Check for:
 - Security vulnerabilities
 - Performance issues
 - Code style violations
 - Missing error handling
3. Generate review report in markdown format
4. Suggest specific fixes for each issue found

2. 知识模板和提示词复用

适用场景：需要将特定的知识结构或提示词模式应用到不同的输入。

technical-doc-writer/
├── SKILL.md
├── references/
│ ├── api-doc-template.md # API 文档模板
│ ├── changelog-template.md # 变更日志模板
│ └── contribution-guide.md # 贡献指南模板

3. 平台特定优化

适用场景：针对特定平台（如 Claude Code）的深度集成优化。

---
name: claude-code-optimization
description: "Claude Code specific workflow optimizations"
---

## Optimization

1. Use Edit tool instead of Write for existing files
2. Batch independent operations together
3. Use TodoWrite for task tracking
4. Follow Git Safety Protocol

决策流程图

 开始
│
▼
需要扩展 AI 能力？
/│\
/ │ \
是 │ 否
/ │ \
▼ │ 不需要扩展
涉及外部系统？
/│\
是 │ 否
/ │ \
▼ │ ▼
跨平台/跨模型？ 固定流程编排？
│ \ │
│ \ │ 是
│ \ │
是 \ ▼
│ \ 使用 Skill
│ \
▼ \
需要系统级访问？
│ \ │
是 \ │
│ \ │
▼ \ │
使用 MCP \ │
│
需要统一安全管控？
/│\
是 │ 否
/ │ \
▼ │ ▼
使用 MCP \ 使用 MCP（标准化要求）
│
需要动态资源发现？
/│\
是 │ 否
/ │ \
▼ │ ▼
使用 MCP \ 根据复杂度选择

实战决策矩阵

决策维度	权重	MCP 评分	Skill 评分	推荐选择
跨平台需求	⭐⭐⭐⭐⭐	5	1	MCP
本地访问	⭐⭐⭐⭐	5	2	MCP
安全管控	⭐⭐⭐⭐⭐	5	1	MCP
系统集成	⭐⭐⭐⭐	5	2	MCP
真实操作	⭐⭐⭐⭐	5	2	MCP
标准化	⭐⭐⭐	5	2	MCP
轻量级	⭐⭐⭐	2	5	Skill
知识复用	⭐⭐⭐	2	5	Skill
平台优化	⭐⭐	1	5	Skill
简单性	⭐⭐	2	4	Skill

混合架构：最佳实践

在实际项目中，MCP 和 Skill 往往是互补而非互斥的：

┌─────────────────────────────────────────────────────────┐
│ AI 客户端 │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Skill 层 │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ 审查流程 │ │ 文档生成 │ │ │
│ │ └──────┬──────┘ └──────┬──────┘ │ │
│ │ │ │ │ │
│ │ └────────┬───────┘ │ │
│ │ ▼ │ │
│ │ 调用 MCP 工具 │ │
│ └──────────────────┬─────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ MCP 层 │ │
│ │ ┌─────────────┐ ┌─────────────┐ │ │
│ │ │ Git 操作 │ │ 文件读写 │ │ │
│ │ └─────────────┘ └─────────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

示例：代码审查 Skill 调用 MCP Git 工具

---
name: code-review-with-git
description: "Code review that uses MCP Git tools for file operations"
---

## Workflow

1. 使用 MCP 工具获取当前 Git 仓库状态
2. 使用 MCP 工具读取变更的文件内容
3. 在本地执行代码审查分析
4. 生成审查报告
5. 使用 MCP 工具创建 Git commit（如果用户确认）

一句话判断规则

最终，可以用两个问题快速决策：

问题一：这个能力是否涉及"能不能访问、怎么连、谁能连、怎么管”？

是 → 用 MCP

问题二：这个能力主要是关于"怎么做、流程是什么、输出要什么格式"？

是 → 用 Skill

总结

方面	MCP	Skill
本质	连接层协议	认知层封装
强项	跨平台、系统访问、安全管控	流程编排、知识复用
适用	外部系统集成、企业级应用	平台内优化、轻量任务
关系	互补而非互斥	互补而非互斥

在实际架构设计时，建议：

优先使用 MCP 处理所有外部系统集成
使用 Skill 编排任务流程和复用知识模板
混合架构 充分发挥两者优势

参考资料

Claude Plugin 进阶：Marketplace 与项目规则实践

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 15:00:00 +0800

背景

在上文从零构建 Claude Skill中，我们完成了 hugo skill 的基础功能。本文记录二阶段开发：接入 Marketplace 和建立项目规则，以及过程中遇到的问题。

Marketplace 接入

marketplace.json 结构

{
 "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
 "name": "taevas-plugins",
 "version": "0.1.0",
 "description": "Taevas Plugins Marketplace",
 "owner": {
 "name": "743v45",
 "email": "noreply@743v45.com"
 },
 "plugins": [
 {
 "name": "hugo",
 "source": "./plugins/hugo",
 "category": "content",
 "description": "Publish content to Hugo blog..."
 }
 ]
}

关键字段说明：

字段	作用
`$schema`	JSON Schema 验证
`plugins[].source`	相对于 marketplace.json 的插件路径
`plugins[].category`	分类：content/notifications/development 等

插件目录结构规范

从 Skill 升级为 Plugin，需要遵循更严格的目录结构：

plugins/hugo/
├── .claude-plugin/
│ └── plugin.json # 插件元数据
├── skills/
│ └── hugo/ # 以 skill 名称命名的目录
│ ├── SKILL.md # 核心指令
│ ├── references/ # 参考文档
│ └── scripts/ # 脚本工具
└── README.md

遇到的问题

问题一：Skill 目录结构重构

现象： 最初 skills 目录结构混乱，无法正确加载。

原因： Skills 应该放在以 skill 名称命名的子目录中，而不是直接放在 skills/ 下。

解决： 重构目录结构

# 错误 ❌
skills/
├── hugo.md
├── references/
└── scripts/
# 正确 ✓
skills/
└── hugo/
├── SKILL.md
├── references/
└── scripts/

对应的 git commits:

f9be4f6 refactor(hugo): 重构插件目录结构
a6b6426 refactor(hugo): 重构 skill 目录结构

问题二：plugin.json 描述过于简单

现象： 插件加载后功能描述不清晰，用户不知道如何使用。

解决： 扩展 description 字段，详细说明所有使用模式：

{
 "description": "Publish content to Hugo blog. Supports: (1) /hugo alone - check installation, (2) /hugo with content - create/update post, (3) /hugo new <content> - force create, (4) /hugo update <content> - force update, (5) /hugo ... -c - preview with hugo server"
}

问题三：文章更新模式缺失

现象： 只能创建新文章，无法更新已有文章。

解决： 添加三种操作模式

模式	命令	行为
CREATE	`/hugo new <content>`	强制创建，存在则报错
UPDATE	`/hugo update <content>`	强制更新，不存在则报错
AUTO	`/hugo <content>`	搜索匹配文章，让用户选择

实现搜索功能需要扩展 detect_hugo_site.py：

def search_posts(directory: str, keywords: str) -> list:
 """Search posts by title or filename, return sorted by match score."""
 # 计算匹配分数
 # 标题匹配 +20，文件名匹配 +10
 # 分词匹配每个词 +5/+3

项目规则建立

Commit 规范

采用 Conventional Commits：

<type>(<scope>): <description>
类型：feat/fix/refactor/docs/style/test/chore
范围：hugo/sound-hooks 等

目录结构规则

.claude-plugin/
├── marketplace.json # 市场配置（项目根）
└── plugins/
└── <plugin-name>/
├── .claude-plugin/
│ └── plugin.json # 插件元数据
├── skills/
│ └── <skill-name>/
│ ├── SKILL.md
│ ├── references/
│ └── scripts/
└── README.md

文件命名规则

SKILL.md 大写，作为 skill 入口
脚本使用 snake_case: detect_hugo_site.py
参考文档使用 kebab-case: front-matter.md

总结

二阶段开发的核心工作：

接入 Marketplace - 建立 marketplace.json 和目录规范
重构目录结构 - skills 放入以名称命名的子目录
完善功能 - 添加文章搜索和更新模式
建立规则 - commit 规范、目录结构、命名约定

参考资料

Claude Skill 调用触发流程详解

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 12:00:00 +0800

概述

Claude Code 的 Skill 系统通过智能匹配机制，在用户请求时自动加载相关能力。本文深入分析 Skill 的调用触发流程。

三层加载架构

┌─────────────────────────────────────────────────────────┐
│ Claude 上下文 │
├─────────────────────────────────────────────────────────┤
│ Layer 1: Metadata (始终加载) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ hugo: "Publish content to Hugo blog..." │ │
│ │ skill-creator: "Guide for creating skills..." │ │
│ │ pdf: "PDF processing..." │ │
│ │ ... (所有 skill 的 name + description) │ │
│ └─────────────────────────────────────────────────┘ │
│ ↓ │
│ Layer 2: SKILL.md Body (触发后加载) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ # Hugo Blog Publisher │ │
│ │ ## Workflow │ │
│ │ 1. Check Hugo installation │ │
│ │ 2. Determine Hugo site path... │ │
│ └─────────────────────────────────────────────────┘ │
│ ↓ │
│ Layer 3: Bundled Resources (按需加载) │
│ ┌─────────────────────────────────────────────────┐ │
│ │ scripts/detect_hugo_site.py │ │
│ │ references/front-matter.md │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

触发流程详解

阶段一：用户输入解析

用户输入: /hugo 写一篇关于 Go 并发的文章
↓
命令解析: skill = "hugo"
args = "写一篇关于 Go 并发的文章"

阶段二：Metadata 匹配

Claude 在所有已安装 skill 的 description 中搜索匹配项：

# hugo skill 的 description
description: "Publish content to Hugo blog. Use when user invokes /hugo command..."

# 匹配逻辑
/hugo → 匹配 "invokes /hugo command" → 触发 hugo skill

匹配规则：

显式命令 /skill-name 优先匹配
隐式触发通过 description 语义匹配
多个匹配时选择描述最相关的

阶段三：Skill Body 加载

触发后，Claude 加载 SKILL.md 的完整内容：

# Hugo Blog Publisher

## Workflow

1. **Check Hugo installation**
 ```bash
 hugo version

Determine Hugo site path
- Run scripts/detect_hugo_site.py
- Always confirm with user …


### 阶段四：执行工作流

┌──────────────────────────────────────────────────┐ │ 1. 检查 hugo version │ │ ↓ │ │ 2. 运行 detect_hugo_site.py │ │ ↓ │ │ 3. 确认站点路径 │ │ ↓ │ │ 4. 确认文章内容 │ │ ↓ │ │ 5. 读取 front-matter.md (按需) │ │ ↓ │ │ 6. 创建文章文件 │ └──────────────────────────────────────────────────┘


## 关键机制
### 1. Description 是触发核心
```yaml
# 好的 description
description: "PDF processing. Use when user needs to: (1) extract text from PDF, (2) merge PDFs, (3) split PDF..."
# 不好的 description
description: "A skill for PDF" # 太模糊

原则：description 必须包含所有触发条件，因为 SKILL.md body 只有在触发后才加载。

2. 脚本执行路径

SKILL.md 指令
↓
Claude 调用 Bash Tool
↓
python3 /path/to/skill/scripts/xxx.py
↓
返回结构化结果
↓
Claude 解析并继续工作流

3. 按需加载 Reference

# SKILL.md 中的引用
- Front matter format: [references/front-matter.md](references/front-matter.md)

Claude 只在需要时读取该文件，避免上下文膨胀。

实际调用示例

用户: /hugo
Claude 内部流程:
1. 解析命令 → skill="hugo"
2. 匹配 metadata → 找到 hugo skill
3. 加载 SKILL.md body
4. 执行 Workflow:
- hugo version → v0.157.0
- detect_hugo_site.py → /Users/xxx/blog
- 确认: "检测到站点，确认？"
- 等待用户输入内容...
用户: 写一篇 Go 教程
Claude 继续:
- 生成内容大纲
- 确认内容
- 读取 front-matter.md
- 创建文件

性能优化

上下文占用

组件	大小	加载频率
所有 metadata	~2KB	始终
单个 SKILL.md	2-10KB	触发后
references/	任意	按需

最佳实践

控制 description 长度：100-200 词最佳
SKILL.md < 500 行：超出部分放入 references
脚本优于重复代码：脚本不占用上下文

总结

Skill 调用流程的核心是渐进式披露：

Metadata 始终在场，负责匹配
Body 触发后加载，提供工作流
Resources 按需读取，提供细节

这种设计在功能和上下文效率之间取得了平衡。

参考资料

从零构建 Claude Skill：以 Hugo 博客发布为例

di4urp@gmail.com (taevas) — Thu, 12 Mar 2026 12:00:00 +0800

背景

Claude Code 支持 Skill 系统，允许用户创建可复用的能力模块。本文以实际创建的 hugo skill 为例，详解 Skill 的构建过程。

什么是 Skill

Skill 是 Claude Code 的扩展机制，本质是一个包含指令和资源的目录：

skill-name/
├── SKILL.md # 核心：YAML frontmatter + Markdown 指令
├── scripts/ # 可执行脚本
├── references/ # 参考文档
└── assets/ # 输出资源

创建步骤

第一步：定义使用场景

明确 skill 要解决的问题。以 hugo skill 为例：

场景	用户输入	预期行为
检查环境	`/hugo`	检测 Hugo 安装和站点
创建文章	`/hugo 写一篇 Go 教程`	生成内容并发布
指定路径	`/hugo --path ~/myblog`	使用指定站点

第二步：规划资源需求

分析需要哪些辅助资源：

hugo/
├── scripts/
│ └── detect_hugo_site.py # 检测 Hugo 站点
├── references/
│ └── front-matter.md # Front matter 格式参考
└── SKILL.md

脚本的作用：检测站点需要遍历目录、检查配置文件，逻辑复杂，用 Python 脚本更可靠。

参考文档的作用：Front matter 有多种格式（TOML/YAML），放入 reference 按需加载。

第三步：编写 SKILL.md

Frontmatter 设计

---
name: hugo
description: "Publish content to Hugo blog. Use when user invokes /hugo command..."
---

description 是触发机制的关键：

必须包含 skill 功能
必须包含触发条件
会被 Claude 持续加载在上下文中

工作流设计

## Workflow

1. **Check Hugo installation**
2. **Determine Hugo site path**
3. **Determine content**
4. **Determine front matter format**
5. **Create the post**

每一步都有明确的指令，包括命令示例和预期输出。

第四步：实现脚本

# scripts/detect_hugo_site.py
def is_hugo_site(directory: str) -> dict:
 # 检查 config.toml / hugo.toml / config.yaml
 config_names = ["config", "hugo"]
 config_extensions = [".toml", ".yaml", ".yml", ".json"]

 # 返回检测结果
 return {
 "is_hugo_site": bool,
 "config_file": str,
 "content_dir": str,
 "existing_posts": list
 }

第五步：验证和迭代

# 测试脚本
python3 scripts/detect_hugo_site.py /path/to/hugo/site

# 实际调用
/hugo 写一篇测试文章

设计原则

1. 渐进式披露

Skill 采用三层加载机制：

层级	内容	加载时机
Metadata	name + description	始终
SKILL.md body	工作流指令	触发后
references/	详细文档	按需

2. 简洁至上

SKILL.md 应控制在 500 行以内，详细内容放入 references。

3. 自由度匹配

自由度	适用场景	hugo skill 示例
高	多种有效方案	文章内容由 LLM 生成
中	有首选模式	Front matter 格式检测
低	必须精确执行	站点检测脚本

最终结构

hugo/
├── SKILL.md # 2.8KB，核心指令
├── scripts/
│ └── detect_hugo_site.py # 92 行，站点检测
├── references/
│ └── front-matter.md # Front matter 格式参考
└── LICENSE.txt

总结

构建 Skill 的核心是明确场景 → 规划资源 → 精简指令。好的 skill 应该：

在 description 中清晰描述触发条件
用脚本处理确定性任务
用 references 存放详细文档
保持 SKILL.md 精简