16.2 Skills配置选项

约 2062 字大约 7 分钟

SKILL.md 元数据配置

Skills 的配置主要通过 SKILL.md 文件的 YAML 前置元数据来实现。本节详细介绍各种配置选项及其使用方法。

核心元数据字段

必需字段

name

name: my-skill

类型: 字符串
长度: 1-64字符
格式: 小写字母、数字和连字符
约束: 不以连字符开头/结尾，无连续连字符
作用: 唯一标识符，用于引用和组织

description

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files, forms, or document extraction.

类型: 字符串
长度: 1-1024字符
作用: 描述功能和使用时机，帮助 AI 发现
最佳实践: 包含关键词，说明适用场景

可选字段

license

license: Apache-2.0

作用: 指定许可证信息
常见值: Apache-2.0, MIT, BSD, Proprietary
建议: 使用标准许可证名称或许可证文件路径

compatibility

compatibility: Designed for Claude Code (or similar products)

作用: 说明环境要求和兼容性
内容: 产品名称、系统要求、网络访问等
长度: 最多500字符

metadata

metadata:
  author: example-org
  version: "1.0"
  tags: ["pdf", "text-extraction", "forms"]
  homepage: "https://github.com/example/my-skill"

作用: 存储额外元数据
结构: 键值对，支持嵌套
用途: 作者信息、版本、标签等

allowed-tools

allowed-tools: Read, Grep, Bash(python:*)

作用: 限制 Skills 可用的工具
格式: 逗号分隔的工具名称
实验性: 目前支持有限，可能因实现而异

配置示例

基础配置

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files, forms, or document extraction.
---

完整配置

---
name: advanced-pdf-processor
description: Comprehensive PDF processing toolkit. Extract text, fill forms, merge documents, convert formats. Use for any PDF-related tasks including document analysis, form automation, and content extraction.
license: MIT
compatibility: Requires Python 3.8+, works with Claude Code and compatible agents
metadata:
  author: pdf-tools-team
  version: "2.1.0"
  tags: ["pdf", "text-extraction", "forms", "conversion"]
  homepage: "https://github.com/pdf-tools/advanced-pdf-processor"
  repository: "https://github.com/pdf-tools/advanced-pdf-processor"
allowed-tools: Read, Grep, Bash(python:*), Bash(pdftotext:*)
---

配置验证

自动验证

Skills 在加载时会自动验证配置的正确性：

格式验证

YAML 语法正确性
必需字段存在性
字段类型正确性

约束验证

name 格式检查
description 长度检查
compatibility 长度检查

错误处理

系统会对配置进行严格的质量检查，发现问题时会详细报告：

必需字段检查：

验证 name 字段是否存在且格式正确验证 description 字段是否存在且长度合适 2. 验证 name 字段是否存在且格式正确 3. 验证 description 字段是否存在且长度合适 4. 格式验证：

名称只能包含小写字母、数字和连字符描述长度不能超过1024个字符兼容性描述长度不能超过500个字符 5. 名称只能包含小写字母、数字和连字符 6. 描述长度不能超过1024个字符 7. 兼容性描述长度不能超过500个字符 8. 错误收集：将所有发现的问题收集起来，一次性反馈给用户

必需字段检查：

验证 name 字段是否存在且格式正确
验证 description 字段是否存在且长度合适
名称只能包含小写字母、数字和连字符
描述长度不能超过1024个字符
兼容性描述长度不能超过500个字符

错误收集：将所有发现的问题收集起来，一次性反馈给用户

# 克隆仓库
git clone https://github.com/agentskills/agentskills.git
cd agentskills/skills-ref

# 创建虚拟环境并安装
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# 或 .venv\Scripts\activate  # Windows

# 安装工具
pip install -e .

安装完成后，skills-ref 命令将在虚拟环境中可用。

使用 skills-ref 验证配置

# 验证单个 Skill
skills-ref validate my-skill/

# 批量验证目录中的所有 Skills
skills-ref validate skills-dir/

# 生成详细报告（显示所有验证信息）
skills-ref validate my-skill/ --verbose

# 验证失败时查看错误详情
skills-ref validate my-skill/ 2>&1

skills-ref 的其他功能

# 读取 Skill 属性（输出 JSON 格式）
skills-ref read-properties my-skill/

# 生成可用 Skills 的提示 XML
skills-ref to-prompt skill-a/ skill-b/

配置最佳实践

描述编写

# 好的描述示例
description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or .xlsx files.

# 不好的描述示例
description: Helps with data

明确说明功能
包含使用关键词
说明适用场景
保持简洁准确

命名规范

# 推荐命名
name: pdf-text-extractor
name: code-review-assistant
name: api-documentation-generator

# 避免的命名
name: PDF-Extractor  # 大写字母
name: pdf_extractor  # 下划线
name: pdf--extractor # 连续连字符

兼容性声明

# 具体声明
compatibility: Designed for Claude Code (or similar products)

# 条件声明
compatibility: Requires internet access for API calls, works offline for local processing

# 环境要求
compatibility: Requires Python 3.8+, Node.js 16+, or compatible runtime

元数据丰富

metadata:
  # 基本信息
  author: "your-org"
  version: "1.0.0"
  created: "2024-01-01"

  # 分类和标签
  category: "data-processing"
  tags: ["pdf", "text", "extraction", "automation"]

  # 联系方式
  homepage: "https://example.com/my-skill"
  repository: "https://github.com/example/my-skill"
  issues: "https://github.com/example/my-skill/issues"

  # 技术信息
  runtime: "python"
  dependencies: ["PyPDF2", "pandas"]

allowed-tools: ToolName, ToolName(parameters), ToolName(pattern:*)

工具类型

基础工具: Read, Write, Grep, Glob
带参数工具: Bash(command:*), RunCommand(timeout:30)
通配符模式: Bash(python:), Bash(node:)

配置示例

# 基本文件操作
allowed-tools: Read, Write, Grep, Glob

# 脚本执行权限
allowed-tools: Bash(python:*), Bash(node:*), Bash(jq:*)

# 受限权限
allowed-tools: Read, Grep

# 完全权限（不推荐）
allowed-tools: all

安全考虑

最小权限原则

只授予必要的工具权限
避免过度宽泛的权限
定期审查和更新权限

风险评估

# 高风险工具
allowed-tools: Bash(rm:*), Bash(dd:*), Bash(format:*)

# 中风险工具
allowed-tools: Bash(curl:*), Bash(wget:*)

# 低风险工具
allowed-tools: Read, Grep, Glob

# .claude/skills.yaml
skills:
  pdf-processing:
    # 覆盖默认配置
    timeout: 60
    max_file_size: "10MB"

用户级配置

# ~/.claude/skills.yaml
skills:
  pdf-processing:
    # 用户偏好
    output_format: "markdown"
    verbose: true

配置合并

配置按以下优先级合并：

SKILL.md 元数据（最高优先级）
用户配置
项目配置
全局配置
默认值（最低优先级）

# 设置超时时间
export CLAUDE_SKILL_TIMEOUT=120

# 启用调试模式
export CLAUDE_SKILL_DEBUG=true

命令行参数

# 运行时指定参数
claude --skill pdf-processing --timeout 60 --verbose

条件配置

基于上下文的条件配置：

metadata:
  config_conditions:
    # 大文件特殊处理
    large_files:
      condition: "file_size > 10MB"
      timeout: 300
      memory_limit: "2GB"

    # 网络限制环境
    offline_mode:
      condition: "network_unavailable"
      disable_network_features: true

# 清除缓存
claude --clear-cache

# 检查配置优先级
claude --show-config pdf-processing

验证失败

现象: Skill 无法加载，提示验证错误原因: 配置格式错误解决:

# 详细验证
skills-ref validate my-skill/ --verbose

# 检查错误详情
skills-ref validate my-skill/ 2>&1

权限不足

现象: 工具调用被拒绝原因: allowed-tools 配置不正确解决:

# 检查并修正权限配置
allowed-tools: Read, Write, Grep, Bash(python:*)

调试命令

# 显示当前配置
claude --show-config

# 显示技能特定配置
claude --show-config pdf-processing

# 验证配置语法
claude --validate-config my-skill/

# 调试模式运行
claude --debug --skill pdf-processing

总结

Skills 的配置通过 SKILL.md 文件的元数据实现，提供了灵活而强大的定制能力。通过合理使用各种配置选项，可以根据具体需求优化 Skills 的行为，确保最佳的用户体验和功能效果。

技术说明：本章中的配置示例是为了帮助您理解原理而提供的。实际使用时，您只需要关注核心配置概念，系统会处理验证和应用。