5. Claude Code Skills全量实战

5.1 核心定义与运行机制

Claude Code Skills 是 Anthropic 推出的 AI 编程功能扩展机制，核心是通过加载包含指令和资源的标准化文件夹（核心文件为SKILL.md，大小写敏感、不可更名），将代码审查、文档生成、批量重构等标准化任务封装为可复用技能，实现按需加载、跨平台复用、自动化执行，彻底解决传统提示词零散、不可复用、执行不稳定的问题。

5.1.1 核心功能

标准化任务封装：将复杂开发流程拆解为固定步骤，固化为技能指令，保证执行一致性。
渐进式披露机制：分阶段加载资源，优先加载元数据，按需加载核心指令与附件，优化算力消耗。
跨平台复用：技能包可在 Claude Web 端、桌面端、CLI 工具中通用，支持 GitHub 分发共享。
多场景自动化：覆盖代码审查、API 文档生成、项目初始化、批量代码重构、测试用例编写等高频场景。
上下文感知：结合项目代码库、历史对话，精准执行技能指令，输出贴合业务的定制化成果。

5.1.2 四层运行机制

发现阶段：启动 Claude 时，预加载所有技能包的元数据（名称、描述），建立技能索引库
激活阶段：用户发起需求后，Claude 匹配技能描述，自动激活对应技能包
执行阶段：加载 SKILL.md 核心指令，按需读取 scripts、references 等附件，按既定流程执行任务
反馈阶段：输出标准化成果，支持一键复用、修改、二次优化，形成执行闭环

5.2 技能包标准化创建规范

5.2.1 标准化文件夹结构

一个完整的 Claude Code Skills 技能包为独立文件夹，命名采用kebab-case（短横线分隔、禁止空格 / 大写 / 下划线），核心结构如下：

python-code-review/
├── SKILL.md          # 必需：核心指令文件（大小写敏感，不可更名）
├── scripts/          # 可选：辅助执行脚本（Python/Shell）
│   └── lint-check.py
├── references/       # 可选：规范文档、API手册、代码模板
│   └── pep8-spec.md
└── assets/           # 可选：配置文件、模板资源
    └── report-template.md

5.2.2 SKILL.md 编写规范

SKILL.md 采用YAML 元数据 + Markdown 指令结构，是技能包的核心中枢，编写规则如下：

---
## 必需元数据
name: python-code-review  # 技能名，必须与文件夹名完全一致
description: 对Python代码进行PEP8规范审查、漏洞检测、可读性优化，适用于后端代码提交前校验
## 可选元数据
version: 1.0.0
author: 技术团队
tags: [Python, 代码审查, 规范校验]
---


## Python代码审查技能
## 执行目标
严格遵循PEP8规范，检测代码语法漏洞、冗余逻辑、命名不规范问题，输出结构化审查报告。


## 执行步骤
1. 读取待审查Python代码，解析语法结构
2. 校验变量命名、缩进、注释、空行等规范
3. 检测潜在bug（如未捕获异常、内存泄漏）
4. 给出优化建议与修改后的代码片段
5. 生成Markdown格式审查报告


## 输出要求
报告需包含：问题等级（高危/中危/低危）、问题位置、违规规范、优化方案

5.3 技能包加载、使用与管理

创建技能包：按规范新建文件夹，编写 SKILL.md 及配套附件资源。
加载技能：在 Claude Code 界面，点击「Skills」→「Load Skill」，选择目标技能包文件夹。
触发技能：输入对应需求指令（如 “审查这段 Python 后端代码”），Claude 自动匹配并激活技能。
执行与复用：查看输出成果，支持一键应用优化代码、保存审查报告；技能包可导出共享，其他开发者直接加载即可复用。
技能管理：无需使用时可点击「Unload Skill」卸载，更新版本后重新加载即可生效。

5.4 完整实战案例：Python 代码审查技能包

5.4.1 需求背景

后端团队开发 Python 接口时，常出现 PEP8 规范不达标、注释缺失、潜在 bug 等问题，人工审查耗时耗力且标准不统一。通过封装 Claude Code Skills 技能包，实现代码提交前自动化合规校验 + 结构化报告输出，统一团队审查标准，降低 CodeReview 沟通成本。

5.4.2 技能包完整文件夹结构

python-code-review/
├── SKILL.md                 # 核心技能指令（完整版）
├── scripts/
│   └── lint-check.py        # Python自动化校验脚本
├── references/
│   └── pep8-spec.md         # PEP8规范精简版（AI参考文档）
└── assets/
    └── report-template.md   # 标准化审查报告模板

5.4.3 核心文件完整可运行代码

① SKILL.md 完整版（核心指令）

---
## 必需元数据
name: python-code-review
description: 对Python后端代码进行PEP8规范校验、语法漏洞检测、可读性优化、安全隐患排查，输出可落地的结构化审查报告，适用于代码提交前、CodeReview环节
## 可选元数据
version: 1.0.0
author: 后端技术组
tags: [Python, Flask, Django, PEP8, 代码审查, 安全校验]
---


## Python代码自动化审查技能
## 技能定位
专为Python后端项目打造的标准化审查工具，兼顾规范合规性、代码安全性、可读性三大核心，替代人工初审，降低CodeReview沟通成本。


## 执行目标
1. 严格校验PEP8编码规范，标记所有违规项
2. 检测语法错误、未捕获异常、冗余代码、无效注释
3. 排查变量命名不规范、缩进错误、空行缺失、魔法数字
4. 生成分级整改报告（高危/中危/低危），附带可直接复制的优化代码
5. 适配Flask/Django等主流后端框架，兼容Python3.8+版本


## 执行步骤
1. 读取用户上传的Python代码文件/代码片段，解析语法结构
2. 调用scripts/lint-check.py脚本做基础语法校验
3. 结合references/pep8-spec.md规范做细节合规校验
4. 分级判定问题风险，标记问题位置、违规原因、整改方案
5. 套用assets/report-template.md模板，生成结构化审查报告
6. 输出优化后的完整代码片段，支持一键替换


## 输出要求
1. 报告采用Markdown格式，分级展示问题，优先级清晰
2. 每个问题需包含：文件名/代码行号、问题描述、违规规范、风险等级、优化方案、修改后代码
3. 结尾附加整体合规率、优化建议总结
4. 无问题时输出「代码合规通过」提示，无冗余内容


## 禁用行为
禁止修改业务逻辑、禁止删除核心代码、禁止新增无关依赖，仅做规范优化与漏洞修复

② scripts/lint-check.py 辅助校验脚本

#!/usr/bin/env python3
## -*- coding: utf-8 -*-
"""
Python代码基础校验脚本
配合Claude Code Skills使用，提前过滤语法错误、基础规范问题
依赖：pylint、pyflakes
安装依赖：pip install pylint pyflakes
"""
import sys
import subprocess
import json


def code_lint_check(file_path: str = None, code_str: str = None) -> dict:
    """
    代码校验入口
    :param file_path: 代码文件路径
    :param code_str: 代码字符串（二选一）
    :return: 校验结果字典
    """
    result = {
        "syntax_error": False,
        "error_list": [],
        "warning_list": []
    }
    try:
        # 临时文件写入（处理代码字符串场景）
        temp_file = "temp_code.py"
        if code_str and not file_path:
            with open(temp_file, "w", encoding="utf-8") as f:
                f.write(code_str)
            target_file = temp_file
        else:
            target_file = file_path


        # 调用pyflakes检测语法错误
        flakes_res = subprocess.run(
            ["pyflakes", target_file],
            capture_output=True,
            text=True,
            encoding="utf-8"
        )
        if flakes_res.stdout:
            result["syntax_error"] = True
            result["error_list"] = [line.strip() for line in flakes_res.stdout.split("\n") if line.strip()]


        # 调用pylint检测规范问题
        pylint_res = subprocess.run(
            ["pylint", "--disable=all", "--enable=E,W", "--output-format=text", target_file],
            capture_output=True,
            text=True,
            encoding="utf-8"
        )
        if pylint_res.stdout:
            result["warning_list"] = [line.strip() for line in pylint_res.stdout.split("\n") if line.strip() and ":" in line]


        # 清理临时文件
        if code_str and not file_path and "temp_code.py" in target_file:
            import os
            os.remove(temp_file)


    except Exception as e:
        result["error_list"].append(f"脚本执行异常：{str(e)}")
    return result


if __name__ == "__main__":
    # 命令行调用：python lint-check.py 目标文件.py
    if len(sys.argv) < 2:
        print(json.dumps({"error": "请传入Python代码文件路径"}))
        sys.exit(1)
    check_result = code_lint_check(file_path=sys.argv[1])
    print(json.dumps(check_result, ensure_ascii=False, indent=2))

③ references/pep8-spec.md 规范参考文档

## Python PEP8 核心规范（审查专用）
## 1. 命名规范
- 变量/函数/方法：小写+下划线（snake_case），禁止拼音、单字符（除循环变量i/j）
- 类名：大驼峰（CamelCase），禁止下划线
- 常量：全大写+下划线（UPPER_SNAKE_CASE）
- 禁止使用关键字、内置函数名作为变量名


## 2. 格式规范
- 缩进：4个空格，禁止使用Tab
- 行宽：单行不超过88字符
- 空行：函数之间空2行，类内方法之间空1行
- 导入：标准库→第三方库→本地模块，分组导入，每组空一行


## 3. 注释规范
- 函数/类必须添加文档字符串（docstring），说明功能、参数、返回值
- 复杂逻辑行添加单行注释，禁止无意义注释
- 注释使用中文，避免英文拼写错误


## 4. 代码安全
- 禁止裸except捕获所有异常，需指定异常类型
- 禁止硬编码密码、密钥、IP等敏感信息
- 避免无限循环、内存泄漏、无效代码块

④ assets/report-template.md 报告模板

## Python代码审查报告
**审查时间**：{time}
**审查文件**：{file_name}
**合规率**：{compliance_rate}%


## 🔴 高危问题（需立即修复）
{high_risk}


## 🟡 中危问题（建议本轮修复）
{medium_risk}


## 🟢 低危问题（后续优化）
{low_risk}


## ✅ 优化后代码片段
```python
{optimized_code}

5.4.4 技能包加载与执行步骤

环境准备：安装脚本依赖，执行pip install pylint pyflakes
加载技能：Claude Code界面点击「Skills」→「Load Skill」，选中python-code-review文件夹
触发审查：上传Python代码文件/粘贴代码片段，输入指令「执行Python代码审查」
结果输出：Claude自动调用脚本+规范文档，10秒内生成完整审查报告，同步输出优化代码

5.5 使用技巧与避坑指南

核心技巧：
- SKILL.md元数据描述要精准，包含“功能+触发条件”，提升模型匹配率
- 指令分层级编写，用标题拆分步骤，避免冗长文本
- 控制token消耗，仅加载必要资源，删除冗余内容
- 技能包按场景分类，便于管理和快速调用

避坑要点：
- SKILL.md必须区分大小写，不可随意更名
- 文件夹命名禁用空格、下划线、大写字母
- 避免指令过于模糊，否则会导致执行偏差
- 大体积附件单独存放，不要全部写入SKILL.md占用算力
- 脚本文件需赋予执行权限，避免调用失败

w3cschool 编程狮，随时随地学编程

5. Claude Code Skills全量实战

5.1 核心定义与运行机制

5.1.1 核心功能

5.1.2 四层运行机制

5.2 技能包标准化创建规范

5.2.1 标准化文件夹结构

5.2.2 SKILL.md 编写规范

5.3 技能包加载、使用与管理

5.4 完整实战案例：Python 代码审查技能包

5.4.1 需求背景

5.4.2 技能包完整文件夹结构

5.4.3 核心文件完整可运行代码

5.4.4 技能包加载与执行步骤

5.5 使用技巧与避坑指南