Skill 从入门到精通——第二章 Skills 规范详解

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

skill-name/
├── SKILL.md          # 必需：技能元数据 + 执行逻辑指令
├── scripts/          # 可选：可执行脚本、代码片段
│   ├── validate.py   # 输入验证脚本
│   └──  generate.py  # 代码/文档生成脚本
├── references/       # 可选：参考文档、领域知识、说明文档
│   ├── api-guide.md  # 示例：API指南
│   └── examples/     # 示例：使用案例目录
├── assets/           # 可选：模板、图片、配置文件、静态资源
└── ...               # 其他自定义文件/目录

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

---
# ===== 必需字段 =====
name: skill-identifier               # 唯一标识（kebab-case）
description: "明确功能、触发条件和排除场景"  # 关键！决定触发准确率

# ===== 推荐字段 =====
license: MIT                         # 开源协议名称或许可证文件路径  
compatibility:                       # 兼容平台声明
  - claude.ai                        # Web 界面
  - claude-code                      # 终端工具

# ===== 可选字段 =====
allowed-tools:                       # 能力边界控制
  - read
  - write
  - bash
metadata:
  url: example.org
  author: example-org
  version: "1.0"
---

1
2
3

name: pdf-processing
name: data-analysis
name: code-review

1
2
3

name: PDF-Processing   # 大写字母不允许
name: -pdf             # 不能以连字符开头
name: pdf--processing  # 连续连字符非法

1
2

# ✅ 好的描述 - 具体、包含触发条件和排除场景
description: "从 PDF 提取文本与表格、填写表单、合并多页 PDF。适用于用户需要处理 PDF、文档解析、表单填写等场景。"

1
2

# ❌ 差的描述 - 模糊、缺乏具体触发条件
description: "处理 PDF 相关事宜"

1

license: 专有许可证。完整条款见 LICENSE.txt 文件

1
2

compatibility: 适用于 Claude Code（或同类产品）
compatibility: 需要安装 git、docker、jq，且需具备互联网访问权限

1
2
3
4

metadata:
  url: example.org
  author: example-org
  version: "1.0"

1

allowed-tools: Bash(git:*) Bash(jq:*) Read Write

1
2
3
4

---
name: pdf-processing
description: 用于 PDF 文本提取、表单填写与文档合并。
---

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

---
name: pdf-processing
description: 从 PDF 文件中提取文本、表格，填写表单并合并文档。适用于用户上传 PDF、需要解析或编辑 PDF 的场景。
version: "1.0"
license: Apache-2.0
compatibility: 需要 Python 及 PyPDF2 环境
metadata:
  url: example-org
allowed-tools: Bash Python Read Write
---

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

---
name: your-skill
description: [你的技能描述]
---

## overview
[简要说明本技能的核心作用、适用场景与预期效果]

## 执行步骤
1. [步骤1：输入解析与校验]
   [...可写明脚本执行命令]
2. [步骤2：核心逻辑执行与资源调用]
3. [步骤3：结果加工与格式整理]
4. [步骤4：输出返回与状态记录]

## 输入输出示例
### 输入格式
[示例输入内容或结构]

### 输出格式
[示例输出内容或结构]


## 边缘情况处理
- 情况1：[输入缺失/格式错误] → 处理方案：[具体应对逻辑]
- 情况2：[调用失败/超时无返回] → 处理方案：[具体应对逻辑]
- 情况3：[结果为空/不符合预期] → 处理方案：[具体应对逻辑]

## 约束与注意事项
[执行限制、权限要求、安全规则、禁用行为等]

## 预期输出结果
Expected output：[描述成功执行后的结果]

1
2
3
4

## 可用脚本

- **`scripts/validate.sh`** — 校验配置文件
- **`scripts/process.py`** — 处理输入数据

1
2
3
4
5

详情请参阅[参考指南](references/REFERENCE.md)。

运行提取脚本：
```bash
python scripts/extract.py

1

skills-ref validate ./my-skill

1

官方说明：该工具仅用于个人验证，不建议生产环境使用，协议 Apache 2.0。

1
2

git clone https://github.com/agentskills/agentskills.git
cd agentskills/skills-ref

1
2
3
4
5
6
7
8

# 创建 Python 虚拟环境，目录名为 .venv
python -m venv .venv

# 激活虚拟环境（macOS/Linux 专用命令）
source .venv/bin/activate

# 以可编辑模式安装当前项目（skills-ref）及其依赖
pip install -e .

1
2
3
4
5

# 使用 uv 快速创建虚拟环境并安装所有依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate

1
2
3
4
5
6
7
8

# 创建虚拟环境
python -m venv .venv

# 在 PowerShell 中激活虚拟环境
.venv\Scripts\Activate.ps1

# 安装项目依赖
pip install -e .

1
2

# 为当前用户允许运行本地脚本，解决 PowerShell 执行策略限制
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

1
2
3
4
5
6
7
8

# 创建虚拟环境
python -m venv .venv

# 在 CMD 中激活虚拟环境
.venv\Scripts\activate.bat

# 安装项目依赖
pip install -e .

1
2
3
4
5

# uv 一键创建环境+安装依赖
uv sync

# 激活虚拟环境
.venv\Scripts\Activate.ps1

1
2

# 查看 skills-ref 命令帮助，检查是否安装成功
skills-ref --help

1
2
3
4
5
6
7
8

# 验证技能
skills-ref validate path/to/skill

# 读取技能元数据（输出 JSON）
skills-ref read-properties path/to/skill

# 为 Agent 提示词生成 <available_skills> 格式 XML
skills-ref to-prompt path/to/skill-a path/to/skill-b

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# 导入路径处理工具
from pathlib import Path
from skills_ref import validate, read_properties, to_prompt

# 验证技能目录是否合法（检查格式、缺失字段等）
# my-skill 是你的技能文件夹路径，可自行修改
problems = validate(Path("my-skill"))
if problems:
    print("Validation errors:", problems)

# 读取技能的元信息（名称、描述、参数等）
props = read_properties(Path("my-skill"))
print(f"Skill: {props.name} - {props.description}")

# 为多个技能生成可直接给 AI 使用的提示词
# 支持传入多个技能路径：skill-a、skill-b 可替换成真实路径
prompt = to_prompt([Path("skill-a"), Path("skill-b")])
print(prompt)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

---
name: brand-guidelines
description: Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
license: Complete terms in LICENSE.txt
---

# Anthropic Brand Styling

## Overview

To access Anthropic's official brand identity and style resources, use this skill.

**Keywords**: branding, corporate identity, visual identity, post-processing, styling, brand colors, typography, Anthropic brand, visual formatting, visual design

## Brand Guidelines

### Colors

**Main Colors:**

- Dark: `#141413` - Primary text and dark backgrounds
- Light: `#faf9f5` - Light backgrounds and text on dark
- Mid Gray: `#b0aea5` - Secondary elements
- Light Gray: `#e8e6dc` - Subtle backgrounds

**Accent Colors:**

- Orange: `#d97757` - Primary accent
- Blue: `#6a9bcc` - Secondary accent
- Green: `#788c5d` - Tertiary accent

### Typography

- **Headings**: Poppins (with Arial fallback)
- **Body Text**: Lora (with Georgia fallback)
- **Note**: Fonts should be pre-installed in your environment for best results

## Features

### Smart Font Application

- Applies Poppins font to headings (24pt and larger)
- Applies Lora font to body text
- Automatically falls back to Arial/Georgia if custom fonts unavailable
- Preserves readability across all systems

### Text Styling

- Headings (24pt+): Poppins font
- Body text: Lora font
- Smart color selection based on background
- Preserves text hierarchy and formatting

### Shape and Accent Colors

- Non-text shapes use accent colors
- Cycles through orange, blue, and green accents
- Maintains visual interest while staying on-brand

## Technical Details

### Font Management

- Uses system-installed Poppins and Lora fonts when available
- Provides automatic fallback to Arial (headings) and Georgia (body)
- No font installation required - works with existing system fonts
- For best results, pre-install Poppins and Lora fonts in your environment

### Color Application

- Uses RGB color values for precise brand matching
- Applied via python-pptx's RGBColor class
- Maintains color fidelity across different systems

1
2

# 验证技能是否符合格式规范
skills-ref validate brand-guidelines/SKILL.md

1
2

# 读取技能元数据（输出 JSON）
skills-ref read-properties brand-guidelines/SKILL.md

1
2

# 为 Agent 提示词生成 <available_skills> 格式 XML
skills-ref to-prompt brand-guidelines/SKILL.md