Skill Authoring

Skill Authoring Guide

编写符合 Agent Skills 规范的 Claude Code Skill。

Use This Skill When

• 创建新的 Claude Code Skill
• 审查现有 Skill 的结构和规范性
• 调试 Skill 验证失败的问题
• 理解 Skill 文件组织和最佳实践

Skill 结构

一个标准的 Skill 目录结构：

.agents/skills//
├── SKILL.md              # 主文件（必需）
├── skill.lock.json       # 锁定文件（推荐）
├── evals/
│   └── evals.json        # 测试用例（推荐）
├── references/           # 参考资料（可选）
│   └── spec.md
├── scripts/              # 辅助脚本（可选）
│   └── validate.sh
└── templates/            # 模板文件（可选）
    └── snippet.md

SKILL.md 格式

Frontmatter（必需）

---
name: skill-name                          # 小写字母、数字、连字符
description: '简短描述，说明用途和触发时机。'  # 1-1024 字符，需引号
license: MIT                              # 开源许可证
metadata:
  author: Your Name
  version: 1.0.0
  tags: "tag1, tag2, tag3"
  repository: https://github.com/...
---

关键规则：

• name：只能使用小写字母、数字、连字符
• description：必须加引号，长度 1-1024 字符，清晰说明何时使用该 skill
• description 是第一段 frontmatter 的 description，不要被示例代码中的 frontmatter 干扰

Body 内容

示例结构：

# Skill 标题

## When to Use / 何时使用

• 触发条件 1
• 触发条件 2

## 核心工作流

1. 步骤一
2. 步骤二
3. 步骤三

## 规则 / Patterns

### 分类一

• 规则 1
• 规则 2

### 分类二 ``bash # 代码示例 ``

## Anti-Patterns（禁止做的事）

• 不要做 X
• 避免 Y

## Scope（适用范围）

Apply to:

• path/pattern/**/*

Do not over-apply to:

• excluded/pattern/**/*

验证 Skill

验证当前 Skill（自验证）

在 skill 目录下运行：

bash scripts/validate_skill.sh

验证其他 Skill

验证指定路径的 skill：

bash .agents/skills/skill-authoring/scripts/validate_skill.sh path/to/your-skill

重要：如果不提供路径参数，脚本只会验证它自己（skill-authoring），而不是你新建的 skill。

验证项

• Frontmatter 格式正确
• Name 字段合法（小写字母、数字、连字符；与目录名一致）
• Description 长度 1-1024 字符且带引号
• License 和 metadata 字段完整
• H1 标题存在
• Body 行数不超过 500（推荐）
• evals.json 存在且合法

常见错误

| 错误 | 原因 | 修复 | |------|------|------| | Description 长度异常 | 脚本读取了示例代码中的 frontmatter | 使用只提取第一段 frontmatter 的 awk 命令 | | Name 包含非法字符 | 使用了大写字母或下划线 | 改为小写和连字符 | | 缺少 H1 标题 | 没有 # Title | 添加一级标题 | | evals.json 格式错误 | JSON 语法错误 | 用 python3 -m json.tool 检查 |

skill.lock.json 格式

{
  "name": "skill-name",
  "version": "1.0.0",
  "lockfileVersion": 1,
  "skill": {
    "name": "skill-name",
    "version": "1.0.0",
    "entry": "SKILL.md",
    "files": [
      "SKILL.md",
      "scripts/helper.sh"
    ],
    "dependencies": {
      "git": ">=2.0.0"
    },
    "checksums": {
      "SKILL.md": "sha256...",
      "scripts/helper.sh": "sha256..."
    }
  },
  "generated": "2026-03-31T00:00:00Z"
}

evals.json 格式

{
  "skill_name": "skill-name",
  "evals": [
    {
      "id": 1,
      "prompt": "测试 prompt",
      "expected_output": "预期输出描述",
      "assertions": ["检查点 1", "检查点 2"]
    }
  ]
}

最佳实践

Do

• 保持 body 在 500 行以内
• 使用具体的文件路径模式
• 提供清晰的代码示例
• 包含 When to Use 章节
• 声明 Anti-Patterns

Don't

• 在 frontmatter 中放代码示例
• 使用过长的 description
• 遗漏 H1 标题
• 创建没有测试用例的 skill

调试技巧

1. 验证脚本报告 description 长度错误：

``bash # 手动计算真实 description 长度 awk '/^---$/ {found++} found==1 && /^description:/ {sub(/^description:[[:space:]]*/, ""); print; exit}' SKILL.md | sed "s/^[\\\"']*//;s/[\\\"']*$//" | wc -c ``

1. 检查 frontmatter 解析问题：

``bash # 确认只提取了第一段 frontmatter awk '/^---$/ {found++} found<=2' SKILL.md ``

1. 生成 checksum：

``bash sha256sum SKILL.md ``

---

参考: https://agentskills.io/specification

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Fldicoahkiin
• Source: Fldicoahkiin/code-alchemist
• License: MIT

Install and usage instructions live in the source repository linked above.