┌─────────────────────────────────────────────────────────┐
│                    Agent Skills 生态                     │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────────┐    ┌─────────────────────────┐    │
│  │  Specification  │    │   Official Repository    │    │
│  │  (规范定义)     │    │   agentskills/agentskills│    │
│  │  agentskills.io │    │   (16.3k Stars)         │    │
│  └────────┬────────┘    └────────────┬────────────┘    │
│           │                              │                │
│           ▼                              ▼                │
│  ┌─────────────────┐    ┌─────────────────────────┐    │
│  │   skills-ref    │    │   Example Skills       │    │
│  │  (Python SDK)   │    │   anthropics/skills    │    │
│  │  验证/读取/转换 │    │   (108.9k Stars)       │    │
│  └────────┬────────┘    └────────────┬────────────┘    │
│           │                              │                │
│           ▼                              ▼                │
│  ┌─────────────────────────────────────────────┐         │
│  │           兼容的 Agent 实现                  │         │
│  │  Claude Code │ Claude.ai │ OpenAI Codex │   │         │
│  │  VS Code Copilot │ 其他兼容实现              │         │
│  └─────────────────────────────────────────────┘         │
└─────────────────────────────────────────────────────────┘

skill-name/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考资料文档
├── assets/           # 可选：静态资源（模板、图片、数据文件）
└── ...               # 任意其他文件或目录

---
name: pdf-processing
description: 提取 PDF 文本和表格、填写表单、合并文件。当处理 PDF 文档或用户提到 PDF、表单、文档提取时使用。
license: Apache-2.0
compatibility: 需要 Python 3.10+ 和 pdfplumber 库
metadata:
  author: example-org
  version: "1.0"
allowed-tools: Bash(python:*) Read
---

# PDF 处理 Skill

[你的指令内容...]

# 合法示例
name: pdf-processing
name: data-analysis
name: code-review

# 非法示例
name: PDF-Processing      # 不能大写
name: -pdf                # 不能以连字符开头
name: pdf--processing     # 不能有连续连字符

# 优秀描述：包含功能 + 激活时机 + 关键词
description: 提取 PDF 文本和表格、填写表单、合并多个 PDF。当处理 PDF 文档、填写表单或文档提取时使用。

# 差劲描述：信息不足
description: Helps with PDFs.

## 使用步骤

1. 安装依赖：`pip install pdfplumber`
2. 使用 `pdfplumber.extract_text()` 提取文本
3. 使用 `pdfplumber.extract_tables()` 提取表格

## 示例

**输入**：`path/to/document.pdf`
**输出**：`{"text": "...", "tables": [...]}`

## 注意事项

- 扫描版 PDF 需要先 OCR
- 加密 PDF 需要先解密

┌──────────────────────────────────────────────────────────┐
│                    渐进式披露流程                          │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  阶段 1：元数据（每个 Skill 约 100 tokens）              │
│  ┌────────────────────────────────────────────────────┐  │
│  │ name + description                                 │  │
│  │ 启动时加载，用于快速匹配和过滤                      │  │
│  └────────────────────────────────────────────────────┘  │
│                          │                               │
│                          ▼                               │
│  阶段 2：指令（推荐 < 5000 tokens）                      │
│  ┌────────────────────────────────────────────────────┐  │
│  │ SKILL.md body                                      │  │
│  │ 激活时加载，完整执行指令                            │  │
│  └────────────────────────────────────────────────────┘  │
│                          │                               │
│                          ▼                               │
│  阶段 3：资源（按需加载）                                │
│  ┌────────────────────────────────────────────────────┐  │
│  │ scripts/、references/、assets/                     │  │
│  │ 仅当执行到相关部分时才加载                          │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
└──────────────────────────────────────────────────────────┘

# 默认 Skill 目录结构
project/
├── .agents/
│   └── skills/           # 默认扫描此目录
│       ├── roll-dice/
│       │   └── SKILL.md
│       ├── pdf-processing/
│       │   └── SKILL.md
│       └── ...

# 1. 用户在 Copilot Chat 中输入
/Roll a d20

# 2. Copilot 发现 roll-dice skill 的 description 匹配
"Roll dice using a random number generator..."

# 3. 激活 Skill，加载完整 SKILL.md（约 500 token）

# 4. 执行技能指令
# Agent 执行：echo $((RANDOM % 20 + 1))
# 返回：15

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

# 使用 uv 安装（推荐）
uv pip install skills-ref

# 或使用 pip
pip install skills-ref

mkdir -p .agents/skills/roll-dice

---
name: roll-dice
description: 使用随机数生成器投骰子。当被问到投骰子（d6、d20 等）、
             roll dice 或生成随机骰子点数时使用。
---

# 投骰子指令

## 使用方法

投掷任意面数的骰子，使用以下命令生成 1 到指定面数之间的随机数：

### Bash（Linux/macOS）

```bash
echo $((RANDOM % <sides> + 1))
```

### PowerShell（Windows）

```powershell
Get-Random -Minimum 1 -Maximum (<sides> + 1)
```

## 参数说明

- `<sides>`：骰子的面数
  - d6：`<sides>` = 6
  - d20：`<sides>` = 20
  - d100：`<sides>` = 100

## 示例

**请求**："Roll a d20"
**命令**：`echo $((RANDOM % 20 + 1))`
**结果**：返回 1-20 之间的随机整数

# 使用 skills-ref 验证 Skill 格式
skills-ref validate .agents/skills/roll-dice

# 验证 Skill 格式
skills-ref validate ./my-skill

# 读取 Skill 属性
skills-ref read-properties ./my-skill

# 生成 prompt
skills-ref to-prompt ./my-skill

git-analysis/
├── SKILL.md
└── scripts/
    └── analyze.py    # 可执行的分析脚本

---
name: git-analysis
description: 分析 Git 仓库的提交历史、贡献者统计和代码变更。
---

## 使用分析脚本

运行 `scripts/analyze.py` 进行深度分析，输出 JSON 格式的统计结果：

```bash
python scripts/analyze.py --repo ./ --format json
```

脚本会返回包含 `total_commits`、`contributors`、`top_contributors` 字段的 JSON。

{
  "total_commits": 1234,
  "contributors": 42,
  "top_contributors": [
    {"name": "alice", "commits": 320},
    {"name": "bob", "commits": 215},
    {"name": "carol", "commits": 180}
  ]
}

pdf-processing/
├── SKILL.md
├── scripts/
│   ├── extract_text.py
│   └── extract_tables.py
└── references/
    ├── API_REFERENCE.md    # 详细的 API 文档
    ├── FORMATS.md         # 支持的 PDF 格式
    └── EXAMPLES.md        # 更多示例

## 详细 API

请参阅 [API 参考文档](references/API_REFERENCE.md) 获取完整的函数签名。

## 示例

更多示例请查看 [示例集](references/EXAMPLES.md)。

document-generator/
├── SKILL.md
└── assets/
    ├── templates/          # 文档模板
    │   ├── report.md
    │   └── memo.md
    ├── images/            # 示例图片
    │   └── flowchart.png
    └── data/             # 数据文件
        └── config.json

---
name: docker-deployment
description: 自动化 Docker 容器部署。当需要构建镜像、部署容器或管理 Docker 环境时使用。
compatibility: 需要 Docker daemon 运行、docker 和 docker-compose 命令可用
---

# 包含多种触发方式
description: 提取 PDF 文本和表格、填写 PDF 表单、合并多个 PDF。
             当用户提到 PDF、表单、文档提取、文本提取时激活。

# 缺少触发词
description: 提取文档内容。

# 清晰说明使用场景
description: 当需要创建符合公司品牌规范的文档（报告、备忘录、邮件）时使用。
             包含公司徽标、配色方案、字体要求。

# 模糊不清
description: 帮助创建文档。

# 简洁主动
description: 验证 API 响应是否符合 OpenAPI 规范。当需要测试 API、
             验证 JSON 响应或检查 REST 端点时使用。

# 冗长被动
description: 这个 Skill 可以被用来进行 API 相关的验证工作，
             它将会检查输入的 JSON 数据是否...

# 精简指令（< 500 行）

## 核心功能
[2-3 句话概括]

## 使用方法
1. 步骤 1
2. 步骤 2

## 示例
[2-3 个典型案例]

## 注意事项
[关键边界情况]

# 冗长指令
[将详细参考全部写入 SKILL.md]

# SKILL.md - 仅保留摘要

## 功能
计算并验证国际标准书号（ISBN-10 和 ISBN-13）。

## 使用
1. 使用 `scripts/validate_isbn.py <isbn>`
2. 脚本返回验证结果

## 示例
- `python scripts/validate_isbn.py 0-306-40615-2` → 有效

## 详细参考
见 `references/isbn_standard.md`

┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│  编写   │───▶│  测试   │───▶│  评估   │───▶│  发布   │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
     │             │             │             │
     ▼             ▼             ▼             ▼
  初步实现    单元测试       A/B 测试      版本发布
            集成测试       用户反馈      监控迭代

import re
from pathlib import Path
from typing import Dict, List

def parse_frontmatter(content: str) -> Dict[str, str]:
    """从 SKILL.md 文本中解析 YAML frontmatter。

    只做最简单的 key: value 提取，不处理多行字符串和嵌套结构。
    生产环境建议改用 PyYAML 或 python-frontmatter 库。
    """
    match = re.match(r"^---\n(.*?)\n---", content, re.DOTALL)
    if not match:
        return {}

    frontmatter: Dict[str, str] = {}
    for line in match.group(1).splitlines():
        if ":" in line:
            key, _, value = line.partition(":")
            frontmatter[key.strip()] = value.strip()
    return frontmatter


def discover_skills(skills_dir: Path) -> List[Dict[str, str]]:
    """扫描目录中的所有 Skill，返回元数据索引。

    Args:
        skills_dir: 存放 Skill 子目录的路径，通常是 .agents/skills/。

    Returns:
        包含 name、description、path 三项的字典列表。
    """
    skills: List[Dict[str, str]] = []

    for skill_path in skills_dir.iterdir():
        if not skill_path.is_dir():
            continue

        skill_md = skill_path / "SKILL.md"
        if not skill_md.exists():
            continue

        frontmatter = parse_frontmatter(skill_md.read_text(encoding="utf-8"))

        skills.append({
            "name": frontmatter.get("name", ""),
            "description": frontmatter.get("description", ""),
            "path": str(skill_path),
        })

    return skills

def activate_skill(skill_path: Path) -> str:
    """加载完整 SKILL.md 内容到上下文。"""
    skill_md = skill_path / "SKILL.md"
    return skill_md.read_text(encoding="utf-8")

def load_skill_resources(skill_path: Path, resource_path: str) -> str:
    """按需加载 Skill 内的脚本或参考文档。

    Args:
        skill_path: Skill 根目录。
        resource_path: 相对于 Skill 根目录的文件路径，如 scripts/extract.py。

    Returns:
        文件文本内容；文件不存在时返回空字符串。
    """
    full_path = skill_path / resource_path
    if full_path.exists():
        return full_path.read_text(encoding="utf-8")
    return ""

---
name: git-workflow
description: 执行标准 Git 工作流程。用于提交代码、创建分支、合并请求等。
allowed-tools: Bash(git:*) Bash(gh:*) Read
---

# Git 工作流 Skill

## 创建分支并提交

1. 使用 `gh auth` 验证 GitHub CLI
2. 执行 `git checkout -b feature/new-feature`
3. 执行 `git add . && git commit -m "feat: add new feature"`

---
name: enterprise-code-review
description: 按照公司安全规范进行代码审查。检查 SQL 注入、XSS、
             敏感信息暴露等安全问题。当需要进行代码审查、
             安全扫描或合规检查时激活。
compatibility: 需要 SonarQube CLI 和公司安全规则库
metadata:
  team: security
  tier: critical
---

# 企业代码审查 Skill

## 安全检查清单

- [ ] SQL 注入防护
- [ ] XSS 输出编码
- [ ] 敏感信息加密存储
- [ ] API 限流实现

---
name: contract-analysis
description: 分析商业合同条款，识别风险点。用于审阅采购合同、
             服务协议、劳动合同等。当用户提到合同审查、
             法律风险或条款分析时激活。
---

# 合同分析 Skill

## 风险识别

### 高风险条款
1. 无限责任条款
2. 竞业禁止过宽
3. 违约金不成比例

### 红旗标志
- "乙方自愿放弃一切诉讼权利"
- "甲方有权随时解除合同"

---
name: ci-pipeline-debug
description: 诊断和修复 CI/CD 流水线问题。用于 GitHub Actions、
             GitLab CI 或 Jenkins 构建失败排查。当构建失败、
             流水线报错或部署问题时激活。
allowed-tools: Bash(git:*) Bash(docker:*) Read
---

# CI/CD 调试 Skill

## 诊断流程

1. 读取 `.github/workflows/*.yml`
2. 分析错误日志
3. 定位问题步骤
4. 提供修复建议

# 声明网络需求
compatibility: 需要互联网访问，用于调用外部 API

---
name: my-skill
description: 功能描述。触发时机。关键词。
license: MIT
compatibility: 需要 Python 3.10+
---

# 技能名

## 使用步骤
1. ...

## 示例
...

# 克隆官方仓库
git clone https://github.com/agentskills/agentskills.git

# 创建新 Skill
cd skills-ref/skills/
mkdir my-new-skill
cd my-new-skill
touch SKILL.md

# 提交 PR
git checkout -b feature/my-new-skill
git add .
git commit -m "feat: add my-new-skill"
git push origin feature/my-new-skill