大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



本文将深入介绍 Skills 的开发规范，以 project-health 技能为实例，介绍Skills在Claude code的使用，详细解读其结构设计、配置参数和实现原理。

---

• project-health 技能示例效果
• 什么是 Skills？
• Skill 文件结构
• Frontmatter 配置详解
• 核心机制解析
• 实战示例：project-health 源码解读
• 使用方法
• **实践

---

• 说明：这个示例是由Claude code 利用 skill-creator 这个官方skill 自动生成。只作为本文档讲解skills开发的用途。
• project-health 生成的代码分析报告示例效果

Skills（技能）是 Claude Code 的扩展机制，允许你为 Claude 添加专业领域能力。通过定义结构化的技能包，Claude 可以：

• 自动触发：当用户请求匹配描述时自动调用
• 手动调用：用户通过 /skill-name 斜杠命令直接使用
• 隔离执行：在独立上下文中运行，不影响主对话

简单来说，一个 Skill 就是一份"专业指南"，告诉 Claude 如何完成特定任务。

---

一个完整的 Skill 目录结构如下：

project-health/ ├── SKILL.md # 主配置文件（必需） ├── reference.md # 详细参考文档 ├── README.md # 技能说明（可选） ├── examples/ │ └── sample-output.md # 示例输出 └── scripts/ └── generate_report.py # 可执行脚本 

┌─────────────────────────────────────────────────────────┐ │ SKILL.md (入口) │ │ ├── Frontmatter: 元数据配置 │ │ └── Markdown: 执行指南 │ │ ├── 引用 reference.md 获取详细文档 │ │ ├── 引用 examples/ 展示用例 │ │ └── 调用 scripts/ 执行具体任务 │ └─────────────────────────────────────────────────────────┘ 

这种分层设计使得：

• 职责分离：配置、文档、代码各司其职
• 易于维护：修改文档不影响配置，更新脚本不影响指南
• 可扩展性：可随时添加新的示例或脚本

---

SKILL.md 文件以 YAML Frontmatter 开头，定义技能的元数据和运行参数。

--- name: project-health description: Analyze project health including code quality, dependencies, git status, and generate visual HTML report. Use when user asks to "check project health", "analyze codebase", "run diagnostics", or "generate project report". argument-hint: [directory] [--fix] [--open] disable-model-invocation: false user-invocable: true allowed-tools: Read, Grep, Glob, Bash(git *), Bash(npm *), Bash(pip *), Bash(python *) model: sonnet context: fork agent: Explore --- 

name - 技能标识

name: project-health 

• 命名规范：小写字母，连字符分隔
• 自动生成 /project-health 命令

description - 触发描述

description: Analyze project health including code quality… 

Claude 使用此字段判断是否应该自动调用此技能。描述应包含：

• 技能功能概述
• 典型触发场景（用户可能说的话）

allowed-tools - 工具白名单

allowed-tools: Read, Grep, Glob, Bash(git ), Bash(npm ), Bash(pip ), Bash(python ) 

支持的格式：

• 单个工具：Read、Write
• 工具组：Bash(git *) 匹配所有 git 命令

安全考虑：限制工具范围可防止误操作，例如只允许 Read 而禁止 Write。

context: fork - 隔离执行

context: fork agent: Explore 

fork 模式创建独立的子代理执行任务：

• 无权访问主对话历史
• 拥有全新的工作内存
• 结果摘要返回主对话

配合 agent: Explore 使用文件探索代理，提供优化的文件系统操作能力。

---

SKILL.md 中可使用动态变量，Claude 会在执行时替换：

 Parameters - $0 (directory): Target directory to analyze - $1 (--fix): Apply automatic fixes - $2 (--open): Open report in browser Running with: directory=`$ARGUMENTS[0]`, fix=`$ARGUMENTS[1]` 

可用变量：

使用 !`command` 语法在加载时执行命令：

 Git Status 

!git status --short 2>/dev/null || echo "Not a git repository"

执行流程：

1. Skill 加载时立即执行命令
2. 命令输出替换占位符
3. Claude 看到的是实际结果，而非命令本身

这使得 Skill 可以获取实时上下文信息。

在 SKILL.md 中调用 scripts 目录下的脚本：

 Step 4: Generate Visual Report Run the bundled visualization script: bash python "${CLAUDE_SKILL_DIR}/scripts/generate_report.py" "$0" --session="${CLAUDE_SESSION_ID}" 

 - `${CLAUDE_SKILL_DIR}` 定位脚本路径 - `$0` 传递用户参数 - `--session=` 传递会话信息用于报告追踪 ---   实战示例：project-health 源码解读  整体架构 

project-health 工作流程 │ ├── 1. 项目检测 (get_project_type) │ └── 识别 package.json, pyproject.toml 等配置文件 │ ├── 2. 文件扫描 (scan_files) │ └── 统计文件数、代码行数、测试覆盖率 │ ├── 3. Git 信息获取 (get_git_info) │ └── 分支、状态、最近提交 │ ├── 4. 依赖检查 (check_dependencies) │ └── 过期依赖、安全漏洞 │ ├── 5. 健康评分计算 (calculate_health_score) │ └── 综合评估，生成 0-100 分 │ └── 6. 报告生成 (generate_html) └── 输出可视化 HTML 报告

  关键代码解析 # 1. 项目类型检测 python def get_project_type(path: Path) -> dict: """Detect project type and framework.""" indicators = { "package.json": ("Node.js", ["react", "vue", "angular", "next", "express"]), "pyproject.toml": ("Python", ["django", "flask", "fastapi", "pytest"]), "go.mod": ("Go", ["gin", "echo", "fiber"]), "Cargo.toml": ("Rust", ["actix", "tokio", "rocket"]), "pom.xml": ("Java", ["spring", "maven"]), } for file, (lang, frameworks) in indicators.items(): if (path / file).exists(): # 检测框架依赖 detected_frameworks = [] if file == "package.json": data = json.loads((path / file).read_text()) deps = ), data.get("devDependencies", {})} for fw in frameworks: if fw in deps: detected_frameworks.append(fw) return {"language": lang, "frameworks": detected_frameworks} return {"language": "Unknown", "frameworks": []} 

设计亮点：

• 使用字典映射配置文件 → 语言类型
• 支持框架检测（如 React、FastAPI）
• 返回结构化信息便于后续处理

2. 健康评分算法

def calculate_health_score(stats: dict, deps: dict, git_info: dict) -> int: """Calculate overall health score (0-100).""" score = 100 # 过期依赖扣分（最多 25 分） if deps["total"] > 0: outdated_ratio = len(deps["outdated"]) / deps["total"] score -= min(25, int(outdated_ratio * 50)) # 缺少测试扣分（最多 15 分） if stats["test_files"] == 0: score -= 15 elif stats["test_files"] < stats["files"] * 0.1: score -= 5 # TODO 过多扣分（最多 10 分） if stats["todo_count"] > 20: score -= min(10, stats["todo_count"] // 10) # 未提交更改扣分（最多 10 分） if git_info["status"]: score -= min(10, len(git_info["status"].splitlines())) # 大文件扣分（最多 10 分） for _, size in stats["largest_files"]: if size > 5 * 1024 * 1024: # 5MB score -= 5 return max(0, min(100, score)) 

评分维度：

3. 智能建议生成

def generate_recommendations(stats: dict, deps: dict, git_info: dict) -> list: """Generate actionable recommendations.""" recommendations = [] if deps["outdated"]: recommendations.append({ "level": "warning", "message": f"更新 {len(deps['outdated'])} 个过期的依赖项以获取最新功能和安全修复" }) if stats["test_files"] == 0: recommendations.append({ "level": "error", "message": "未找到测试文件。添加测试以提高代码可靠性" }) if git_info["status"]: recommendations.append({ "level": "warning", "message": "检测到未提交的更改。建议提交或暂存" }) if not recommendations: recommendations.append({ "level": "success", "message": "项目状态良好！继续保持。" }) return recommendations 

建议分级：

• error 🔴：必须处理的问题
• warning 🟡：建议改进的地方
• success 🟢：状态良好

---

# 分析当前目录 /project-health # 分析指定目录 /project-health ./my-project # 分析并自动修复 /project-health ./my-project --fix # 分析后打开报告 /project-health ./my-project --open 

1. 提交前检查

/project-health . –quick 

在代码提交前快速检查，及早发现问题。

2. 依赖更新

/project-health . –fix 

自动更新过期的依赖包。

3. 新项目评估

/project-health ./unfamiliar-codebase –detailed 

快速了解陌生项目的整体状况。

4. 定期巡检

/loop 1w /project-health . –open 

每周自动执行健康检查。

---

# ✅ 好的实践：清晰的描述，包含触发关键词 description: Analyze project health including code quality, dependencies... Use when user asks to "check project health", "analyze codebase"... # ❌ 不好的实践：模糊的描述 description: Analyze stuff 

# ✅ 最小权限原则 allowed-tools: Read, Grep, Glob, Bash(git status) # ❌ 过度授权（可能危险） allowed-tools: Bash(*) 

在脚本中使用优雅的错误处理：

def run_command(cmd: list, default: str = ””) -> str:

"""Run a shell command and return output.""" try: result = subprocess.run(cmd, capture_output=True, text=True, timeout=30) return result.stdout.strip() if result.returncode == 0 else default except Exception: return default # 返回默认值而非抛出异常 

SKILL.md → 快速指南，执行步骤 reference.md → 详细配置，API 参考 examples/ → 使用示例，输出样例 

不同用户关注不同层次的信息。

---

Skills 是一个强大且灵活的扩展机制。通过本文的 project-health 示例，我们了解了：

1. 文件结构：SKILL.md 为核心，reference.md 和 scripts/ 为支撑
2. Frontmatter 配置：定义技能的元数据、权限和运行模式
3. 核心机制：参数替换、动态上下文注入、脚本调用
4. 实际应用：项目健康检查的完整实现

掌握这些，可以创建自己的 Skills，把自己的专业能力转化为skills！

---

• Claude Code Skills 官方文档