Jacin Blog
AI Skills 开发-1
AI 大模型开发

AI Skills 开发-1

JACIN16 分钟阅读

AI Skills 开发指南#

什么是 Skills？#

Skills 是挂在执行环境上的"任务知识包 / 能力包"。在 OpenAI 的实现中，skills 通常挂在 shell environment 里，但其本质并不是 shell 本身。

Skills 的核心组成#

一个 skill 包含：

  • SKILL.md - 任务定义文件
  • 执行步骤 - 明确的操作流程
  • 策略与约束 - 使用规则和限制
  • 辅助脚本 - 可选的执行脚本（如 Python、Shell 等）

核心概念区分#

概念定义
Tool具体的能力或工具
Skill能力的使用手册和执行指南
MCP能力接入的协议标准

Skill 更像是"带执行环境的 SOP（标准操作流程）"，它告诉 AI 模型面对某类任务时应该按什么步骤去做。

Skills 的官方架构#

目录结构#

text 
my-skill/
├── SKILL.md
└── helper.py

SKILL.md 文件格式#

SKILL.md 是 skill 的核心定义文件，包含 frontmatter 和执行说明：

markdown 
---
name: csv-insights
description: 总结 CSV 文件并输出 markdown 报告。只在任务明确涉及 CSV 汇总、统计、报表时触发。
---

你是一个 CSV 分析技能。

执行步骤：
1. 找到仓库中的 CSV 文件
2. 优先使用 helper.py 做基础统计
3. 输出 markdown 报告，包含：
   - 文件列表
   - 每个文件的行数/列数
   - 关键异常值或空值情况
   - 总结建议

如果没有 CSV 文件，明确说明未发现目标文件。

Frontmatter 必需字段：

  • name - skill 的唯一标识符
  • description - skill 的功能描述

实战示例：多 Skills 配置#

Python 代码示例#

python 
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    tools=[
        {
            "type": "shell",
            "environment": {
                "type": "local",
                "skills": [
                    {
                        "name": "csv-insights",
                        "description": "总结 CSV 文件并输出 markdown 报告。适合处理 CSV 分析、统计、报表类任务。",
                        "path": "./skills/csv-insights",
                    },
                    {
                        "name": "incident-triage",
                        "description": "用于事故排查、日志定位、初步分级。适合处理故障分析、异常定位、SOP 排查类任务。",
                        "path": "./skills/incident-triage",
                    },
                ],
            },
        }
    ],
    input="""
请分析当前项目中的 CSV 文件，并输出一份 markdown 总结报告。
如果合适，请自行选择最适合的 skill。
""",
)

print(response.output_text)

最佳实践#

1. Skill 设计原则#

  • 单一职责 - 每个 skill 专注于一类任务
  • 清晰描述 - description 要准确反映 skill 的触发条件
  • 完整文档 - SKILL.md 中的步骤要详细可执行
  • 模块化脚本 - 辅助脚本应该独立、可复用

2. 命名规范#

  • Skill 名称使用 kebab-case（如 csv-insights）
  • 目录名与 skill name 保持一致
  • 脚本文件名清晰表达功能（如 helper.py、analyzer.sh）

3. 触发策略#

在 description 中明确指定触发条件，帮助模型判断何时使用该 skill：

text 
"description": "仅在任务涉及 [具体场景] 时触发。适合处理 [应用场景]。"

Claude Code 中的 Skills 应用#

Slash Commands 与 Skills 的关系#

在 Claude Code 环境中，skills 通过 slash commands 的形式暴露给用户：

text 
/commit          - 自动化提交管理
/review-pr       - 代码审查
/pdf             - PDF 处理
/ms-office-suite - Office 文档处理

这些都是预置的 skills，用户也可以创建自定义 skills。

自定义 Skill 开发流程#

第一步：创建 Skill 目录结构#

bash 
mkdir -p my-skills/code-formatter
cd my-skills/code-formatter

第二步：编写 SKILL.md#

markdown 
---
name: code-formatter
description: 自动格式化代码文件，支持多种语言。仅在用户明确要求代码格式化时触发。
---

# 代码格式化 Skill

## 功能
- 检测代码语言
- 应用对应的格式化规则
- 输出格式化后的代码

## 执行步骤
1. 识别文件类型和编程语言
2. 选择合适的格式化工具（prettier、black、gofmt 等）
3. 应用格式化规则
4. 返回格式化结果和变更摘要

第三步：编写辅助脚本#

python 
# formatter.py
import subprocess
import os

def detect_language(file_path):
    """检测文件编程语言"""
    ext = os.path.splitext(file_path)[1]
    language_map = {
        '.py': 'python',
        '.js': 'javascript',
        '.ts': 'typescript',
        '.go': 'go',
        '.rs': 'rust',
    }
    return language_map.get(ext, 'unknown')

def format_code(file_path):
    """格式化代码"""
    lang = detect_language(file_path)

    if lang == 'python':
        subprocess.run(['black', file_path])
    elif lang in ['javascript', 'typescript']:
        subprocess.run(['prettier', '--write', file_path])
    elif lang == 'go':
        subprocess.run(['gofmt', '-w', file_path])

    return f"✓ {file_path} 已格式化"

Skills 与 MCP 的协作#

MCP（Model Context Protocol）的角色#

MCP 是一个开放协议，用于连接 AI 模型与外部工具和数据源。Skills 可以通过 MCP 扩展功能：

text 
┌─────────────────┐
│   Claude Code   │
└────────┬────────┘
         │
    ┌────▼─────┐
    │  Skills  │
    └────┬─────┘
         │
    ┌��───▼─────┐
    │    MCP   │
    └────┬─────┘
         │
    ┌────▼──────────────────┐
    │  External Tools/APIs  │
    │  - Databases          │
    │  - APIs               │
    │  - File Systems       │
    └───────────────────────┘

通过 MCP 扩展 Skill 功能#

python 
# 使用 MCP 连接数据库的 skill 示例
from mcp import MCPClient

class DatabaseQuerySkill:
    def __init__(self):
        self.mcp_client = MCPClient()

    def execute(self, query):
        # 通过 MCP 连接数据库
        result = self.mcp_client.call_tool(
            "database_query",
            {"sql": query}
        )
        return result

常见 Skill 模板库#

1. 数据处理 Skill#

markdown 
---
name: data-processor
description: 处理和转换数据文件（CSV、JSON、XML）。适合数据清洗、格式转换任务。
---

支持的操作：
- CSV 到 JSON 转换
- 数据去重和清洗
- 字段映射和转换

2. 文档生成 Skill#

markdown 
---
name: doc-generator
description: 从代码自动生成文档。适合 API 文档、README 生成。
---

支持的文档类型：
- API 文档（OpenAPI/Swagger）
- README 和快速开始指南
- 变更日志（CHANGELOG）

3. 测试辅助 Skill#

markdown 
---
name: test-helper
description: 生成测试用例和测试数据。适合单元测试、集成测试场景。
---

功能：
- 生成测试用例框架
- 创建 Mock 数据
- 覆盖率分析

调试与优化#

常见问题排查#

问题原因解决方案
Skill 未被触发description 不够清晰优化 description，明确触发条件
执行失败脚本依赖缺失检查环境依赖，补充 requirements.txt
性能低下脚本逻辑复杂优化算法，添加缓存机制
输出格式错误返回值格式不符确保返回结构化数据

性能优化建议#

  • 缓存策略 - 对重复操作使用缓存
  • 异步处理 - 长时间操作使用异步执行
  • 增量更新 - 只处理变更部分，避免全量重新计算
  • 资源限制 - 设置超时和内存限制

实战案例：完整的 Skill 开发#

场景：代码质量检查 Skill#

text 
code-quality-checker/
├── SKILL.md
├── checker.py
├── requirements.txt
└── config.yaml

SKILL.md:

markdown 
---
name: code-quality-checker
description: 检查代码质量，包括风格、复杂度、安��问题。仅在需要代码审查时触发。
---

## 检查项
1. 代码风格（PEP 8、ESLint）
2. 圈复杂度
3. 安全漏洞扫描
4. 依赖版本检查

## 输出格式
- 问题列表
- 严重程度分级
- 修复建议

checker.py:

python 
import subprocess
import json

class CodeQualityChecker:
    def check(self, file_path):
        results = {
            "style": self._check_style(file_path),
            "complexity": self._check_complexity(file_path),
            "security": self._check_security(file_path),
        }
        return results

    def _check_style(self, file_path):
        # 使用 pylint、flake8 等工具
        pass

    def _check_complexity(self, file_path):
        # 使用 radon 等工具
        pass

    def _check_security(self, file_path):
        # 使用 bandit 等工具
        pass

总结#

Skills 是 AI 能力扩展的重要机制，通过结构化的 SKILL.md 和执行环境，让 AI 模型能够更系统地处理复杂任务。结合 MCP 协议，skills 可以无缝集成各种外部工具和服务。

关键要点：

  • Skills 本质是"带执行环境的 SOP"
  • 通过 slash commands 在 Claude Code 中使用
  • 可与 MCP 协作扩展功能
  • 遵循设计原则和最佳实践能显著提升应用质量

评论

还没有评论，来发第一个吧