16.2 Skills配置选项

SKILL.md 元数据配置#

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

核心元数据字段#

必需字段#

name

yaml
复制
name: my-skill

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

description

yaml
复制
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

yaml
复制
license: Apache-2.0

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

compatibility

yaml
复制
compatibility: Designed for Claude Code (or similar products)

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

metadata

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

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

allowed-tools

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

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

配置示例#

基础配置#

yaml
复制
---
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.
---

完整配置#

yaml
复制
---
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 长度检查

错误处理

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

1. 必需字段检查：

   • 验证 name 字段是否存在且格式正确
   • 验证 description 字段是否存在且长度合适

2. 格式验证：

   • 名称只能包含小写字母、数字和连字符
   • 描述长度不能超过1024个字符
   • 兼容性描述长度不能超过500个字符

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

验证工具#

skills-ref 工具介绍

skills-ref 是 Agent Skills 规范的官方参考实现工具，由 Anthropic 提供，用于验证 Skills 的格式和配置正确性。

获取和安装 skills-ref

从 Agent Skills 规范的官方 GitHub 仓库获取：

bash
复制
# 克隆仓库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 验证配置

bash
复制
# 验证单个 Skillskills-ref validate my-skill/

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

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

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

skills-ref 的其他功能

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

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

配置最佳实践#

描述编写#

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

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

要点:

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

命名规范#

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

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

兼容性声明#

yaml
复制
# 具体声明
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

元数据丰富#

yaml
复制
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 详解#

语法格式

yaml
复制
allowed-tools: ToolName, ToolName(parameters), ToolName(pattern:*)

工具类型

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

配置示例

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

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

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

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

安全考虑#

最小权限原则

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

风险评估

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

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

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

配置继承和覆盖#

层级配置#

虽然 Skills 主要通过 SKILL.md 配置，但也支持外部配置文件的继承：

项目级配置

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

用户级配置

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

配置合并#

配置按以下优先级合并：

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

动态配置#

运行时配置#

某些配置可以在运行时动态调整：

环境变量

bash
复制
# 设置超时时间exportCLAUDE_SKILL_TIMEOUT=120
# 启用调试模式exportCLAUDE_SKILL_DEBUG=true

命令行参数

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

条件配置#

基于上下文的条件配置：

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

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

配置调试和故障排除#

常见问题#

配置未生效

现象: 修改配置后没有变化 原因: 缓存问题或优先级错误 解决:

bash
复制
# 清除缓存claude --clear-cache

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

验证失败

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

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

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

权限不足

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

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

调试命令#

bash
复制
# 显示当前配置claude --show-config

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

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

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

总结#

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