Skill开发与规范

把一项能力整理成「以技能名为根目录、根目录下必须有 SKILL.md」的文件夹，打成 zip 提交平台，通过解析校验后上架，供智能体按需加载调用。

1. 技能如何被加载

平台按渐进式披露分三级加载，文件怎么放取决于这一节：

级别	加载内容	何时加载	体积建议
L1 元数据	name + description	Agent 启动时常驻（所有已装配技能）	~100 tokens
L2 指令	SKILL.md 正文全文	命中description 时才加载	< 5000 tokens 且 < 500 行
L3 资源	references/、scripts/、assets/	执行中按需读取	单文件小、聚焦、单层引用

2. 基础目录结构

zip 解压后第一层必须且只能是 {skill-name}/：

{skill-name}/                  # 目录名必须等于 frontmatter 的 name
├── SKILL.md                   # ★ 必须：元数据 + 指令正文
├── references/                # 可选：补充知识文档（按需读取）
│   ├── api-spec.md            #   API 规范、字段类型
│   └── examples.md            #   输入输出示例
├── scripts/                   # 可选：可执行脚本
│   ├── fetch-data.py
│   └── transform.py
├── assets/                    # 可选：静态资源（模板、图片、数据文件）
│   ├── report-template.md
│   └── schema.json
└── ...                        # 其他文件（见「多余文件策略」）

项	约束
根目录	第一层必须是{skill-name}/；不得多套一层，不得把 SKILL.md 放在 zip 根
目录名	与 frontmatter 的name 完全一致（大小写敏感），仅小写字母、数字、连字符
必备文件	仅SKILL.md；其余目录均可选
禁止命名	中文、空格、大写
编码	UTF-8（无 BOM），换行 LF
打包体积	包体积 ≤ 50MB（默认值，以提交页提示为准）
必须清理	.git/、node_modules/、venv/、pycache/、__MACOSX/、.DS_Store
依赖	用requirements.txt / package.json 声明；不得打包已安装的依赖目录

其他文件：其他文件原样保留、不会导致解析失败，但占体积，建议只留必需内容。

3. SKILL.md：格式与字段

SKILL.md = YAML frontmatter + Markdown 正文，以 --- 分隔。

3.1 字段表

标准字段（对齐 AgentSkills）

字段	必填	约束	说明
name	是	1–64 字符；仅小写字母、数字、连字符；不得首尾为连字符、不得出现--；必须等于根目录名	技能唯一标识。反例：PDF-Processing、-pdf、pdf--processing
description	是	1–1024 字符，非空	Agent 检索与触发判定的唯一依据：写清「做什么」+「何时用」+ 触发关键词
license	否	许可证名或随包许可证文件名	如Apache-2.0
compatibility	否	1–500 字符	环境依赖，如Requires git, jq, and internet access
metadata	否	字符串键值对	标准预留扩展位；平台已定义字段不要塞这里
allowed-tools	否	空格分隔的工具白名单	如Bash(git:*) Read Write。实验性字段，支持度依 Agent 实现

通用规则：必填字段缺失 = 解析失败，不静默兜底。字段名大小写敏感，连字符组与下划线组不可互换（写 allowed_tools 会被判为未知字段）。

3.2 示例

最小可用（能通过解析、能被触发）：

---
name: pdf-processing
display_name: PDF 处理
description: Extracts text and tables from PDF files, fills forms, merges PDFs. Use when the user mentions PDF, forms, or document extraction.
description_zh: PDF 文本与表格提取、表单填写与合并
description_en: Extract PDF text, fill forms, and merge PDFs.
category: office
version: 1.0.0
author: teleai
delivery: managed
---

# 技能指令正文
当用户需要处理 PDF 时，按以下步骤执行：
1. 运行 `scripts/extract.py` 提取文本；
2. ...

4. 正文编写规范

4.1 写作建议要求

要求	❌ → ✅
祈使句、可执行动作，不寒暄	❌「可以先看下接口」 → ✅「调用GET /v1/orders?status=paid」
一步一动作	❌「处理并校验数据」 → ✅「1) 运行 scripts/clean.py；2) 校验输出行数 > 0」
给出路径、命令、参数	❌「运行脚本」 → ✅「python scripts/extract.py --input <file>」
给判断分支与阈值	❌「视情况重试」 → ✅「返回 429 时等 2s 重试，最多 3 次」
明确失败退出条件	「输出为空则停止并提示用户补充材料」
参数化，不写死具体值	❌ 写死订单号 → ✅{order_id} 由用户提供
控制长度	SKILL.md < 500 行、正文 < 5000 tokens，超出下沉 references/

4.2 引用语法

用技能根目录相对路径，只允许一层：

See [the reference guide](references/api-spec.md) for details.
Run the extraction script: scripts/extract.py

禁止：绝对路径、../ 跳出技能目录、references/ 再引用 references/。正文提到文件名直接写 SKILL.md，不要加超链接

5. 子资源目录

目录	放什么	加载时机	约束
references/	API 字段定义、协议规范、领域知识、示例数据	执行中按需读取	单文件聚焦一个主题
scripts/	调外部 API、数据处理、批量操作等可执行脚本	Agent 经 Bash 调用	自包含或明确声明依赖；错误信息清晰
assets/	报告/配置模板、图片、查找表、JSON Schema	仅被读取，不执行	不放可执行代码

分界：可执行放 scripts/；只被读取的放 references/（知识）或 assets/（模板与静态资源）。

6. 安全红线

6.1 禁止项

类别	禁止内容
凭据	硬编码 AK/SK、token、密码、PRIVATE KEY、数据库连接串；平台只支持环境变量注入，不接收凭据文件
网络	硬编码内网地址、内部域名、回环调用
越权	绕过平台鉴权/计费直连上游
破坏性操作	rm -rf /、无确认的批量删除、把下载的脚本管道给 shell 执行
文件系统	读写技能目录与工作区之外的文件
内容合规	违法违规、涉政敏感、色情低俗、虚假宣传（详见平台《内容发布规范》）

6.2 鉴权声明

1. frontmatter 声明变量名：auth-env: ACME_API_KEY ACME_SECRET（只写名，不写值）；
2. 正文「前置条件」写明每个变量的获取方式与用途；
3. 上架信息填写「鉴权声明」：变量名 + 用途 + 是否必填，值由用户在企业侧配置。

脚本只允许 os.environ["ACME_API_KEY"] 这种读法；禁止硬编码、禁止读凭据文件。

7. 版本与升级

项	规则
格式	semverMAJOR.MINOR.PATCH
MAJOR / MINOR / PATCH	不兼容变更 / 向后兼容新增 / 向后兼容修复（含文案微调）
重复提交	同一name 再次提交，version 必须严格递增，不允许重复或回退
历史版本	平台全量保留，供锁定订阅方与回滚
跟随策略	由订阅方决定：跟随订阅（默认，自动升最新）/ 锁定 pin 到指定版本；不由交付轨道决定
下载型	已落地的副本不自动更新，需企业重新拉取；平台可吊销指定版本

8. 打包与提交

1. 目录名 = frontmatter 的 name（完全一致，小写连字符）；
2. 清理 .git/、node_modules/、venv/、pycache/、__MACOSX/、.DS_Store；
3. 确认 SKILL.md 位于 {skill-name}/ 内，zip 解压后第一层即 {skill-name}/；
4. 编码 UTF-8（无 BOM）、换行 LF；
5. 平台解析校验：通过 → 进审核；失败 → 提交页给报错。

9. 上架前自检清单

• 解压后第一层是 {skill-name}/，目录名 = frontmatter name
• SKILL.md 就位（唯一必需文件）
• name 符合 1–64 字符、小写字母/数字/连字符、首尾非连字符、无 --
• description 含「做什么 + 何时用 + 触发关键词」，≤ 1024 字符
• 必填字段齐全：display_name、description_zh、description_en、category、version、author、delivery
• version 为合法 semver 且严格递增
• 正文含：适用场景 / 执行步骤 / 输入输出示例 / 边界与失败处理
• SKILL.md < 500 行，正文 < 5000 tokens
• 文件引用为相对路径且只有一层
• 无硬编码密钥、连接串、内网地址；凭据走环境变量
• 依赖用清单声明，未打包依赖目录
• .git/、node_modules/、__MACOSX/、.DS_Store 已清理
• 编码 UTF-8（无 BOM）、换行 LF

附录 A：与 AgentSkills 标准对照

• Agent Skills 开放标准：https://agentskills.io/home
• 格式规范全文：https://agentskills.io/specification