技能标准化器
- 作者仓库星标 208
- 许可证 Complete terms in LICENSE.txt
- 作者仓库 AgentJet
- 领域
- 数据
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @modelscope · Complete terms in LICENSE.txt
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Docker
- 运行环境要求
- Python >=3.14 · Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
Your task is to make skills in non-standard formats compatible with the Agent Skills ecosystem by converting them to the standard `SKILL.md` format. This document provides the specification for the `SKILL.md` format, including required and optional fields, directory structure, and best practices for writing effective skills.
---
> ## Documentation Index
> Fetch the complete documentation index at: https://agentskills.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Specification
> The complete format specification for Agent Skills.
## Directory structure
A skill is a directory containing, at minimum, a `SKILL.md` file:
```
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directories
```
## `SKILL.md` format
The `SKILL.md` file must contain YAML frontmatter followed by Markdown content.
### Frontmatter
| Field | Required | Constraints |
| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `name` | Yes | Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. |
| `description` | Yes | Max 1024 characters. Non-empty. Describes what the skill does and when to use it. |
| `license` | No | License name or reference to a bundled license file. |
| `compatibility` | No | Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.). |
| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
| `allowed-tools` | No | Space-separated string of pre-approved tools the skill may use. (Experimental) |
<Card>
**Minimal example:**
```markdown SKILL.md theme={null}
---
name: skill-name
description: A description of what this skill does and when to use it.
---
```
**Example with optional fields:**
```markdown SKILL.md theme={null}
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
author: example-org
version: "1.0"
---
```
</Card>
#### `name` field
The required `name` field:
* Must be 1-64 characters
* May only contain unicode lowercase alphanumeric characters (`a-z`) and hyphens (`-`)
* Must not start or end with a hyphen (`-`)
* Must not contain consecutive hyphens (`--`)
* Must match the parent directory name
<Card>
**Valid examples:**
```yaml theme={null}
name: pdf-processing
```
```yaml theme={null}
name: data-analysis
```
```yaml theme={null}
name: code-review
```
**Invalid examples:**
```yaml theme={null}
name: PDF-Processing # uppercase not allowed
```
```yaml theme={null}
name: -pdf # cannot start with hyphen
```
```yaml theme={null}
name: pdf--processing # consecutive hyphens not allowed
```
</Card>
#### `description` field
The required `description` field:
* Must be 1-1024 characters
* Should describe both what the skill does and when to use it
* Should include specific keywords that help agents identify relevant tasks
<Card>
**Good example:**
```yaml theme={null}
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
```
**Poor example:**
```yaml theme={null}
description: Helps with PDFs.
```
</Card>
#### `license` field
The optional `license` field:
* Specifies the license applied to the skill
* We recommend keeping it short (either the name of a license or the name of a bundled license file)
<Card>
**Example:**
```yaml theme={null}
license: Proprietary. LICENSE.txt has complete terms
```
</Card>
#### `compatibility` field
The optional `compatibility` field:
* Must be 1-500 characters if provided
* Should only be included if your skill has specific environment requirements
* Can indicate intended product, required system packages, network access needs, etc.
<Card>
**Examples:**
```yaml theme={null}
compatibility: Designed for Claude Code (or similar products)
```
```yaml theme={null}
compatibility: Requires git, docker, jq, and access to the internet
```
```yaml theme={null}
compatibility: Requires Python 3.14+ and uv
```
</Card>
<Note>
Most skills do not need the `compatibility` field.
</Note>
#### `metadata` field
The optional `metadata` field:
* A map from string keys to string values
* Clients can use this to store additional properties not defined by the Agent Skills spec
* We recommend making your key names reasonably unique to avoid accidental conflicts
<Card>
**Example:**
```yaml theme={null}
metadata:
author: example-org
version: "1.0"
```
</Card>
#### `allowed-tools` field
The optional `allowed-tools` field:
* A space-separated string of tools that are pre-approved to run
* Experimental. Support for this field may vary between agent implementations
<Card>
**Example:**
```yaml theme={null}
allowed-tools: Bash(git:*) Bash(jq:*) Read
```
</Card>
### Body content
The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.
Recommended sections:
* Step-by-step instructions
* Examples of inputs and outputs
* Common edge cases
Note that the agent will load this entire file once it's decided to activate a skill. Consider splitting longer `SKILL.md` content into referenced files.
## Optional directories
### `scripts/`
Contains executable code that agents can run. Scripts should:
* Be self-contained or clearly document dependencies
* Include helpful error messages
* Handle edge cases gracefully
Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.
### `references/`
Contains additional documentation that agents can read when needed:
* `REFERENCE.md` - Detailed technical reference
* `FORMS.md` - Form templates or structured data formats
* Domain-specific files (`finance.md`, `legal.md`, etc.)
Keep individual [reference files](#file-references) focused. Agents load these on demand, so smaller files mean less use of context.
### `assets/`
Contains static resources:
* Templates (document templates, configuration templates)
* Images (diagrams, examples)
* Data files (lookup tables, schemas)
## Progressive disclosure
Agents load skills *progressively*, pulling in more detail only as a task calls for it. Skills should be structured to take advantage of this:
1. **Metadata** (\~100 tokens): The `name` and `description` fields are loaded at startup for all skills
2. **Instructions** (\< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated
3. **Resources** (as needed): Files (e.g. those in `scripts/`, `references/`, or `assets/`) are loaded only when required
Keep your main `SKILL.md` under 500 lines. Move detailed reference material to separate files.
## File references
When referencing other files in your skill, use relative paths from the skill root:
```markdown SKILL.md theme={null}
See [the reference guide](references/REFERENCE.md) for details.
Run the extraction script:
scripts/extract.py
```
Keep file references one level deep from `SKILL.md`. Avoid deeply nested reference chains.
## Validation
Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) reference library to validate your skills:
```bash theme={null}
skills-ref validate ./my-skill
```
This checks that your `SKILL.md` frontmatter is valid and follows all naming conventions.
章节与文件索引
按说明文件中的顺序排列。
目录结构
技能.md 格式
前题
正文内容
脚本/
文件/命令 -> name · description · license · compatibility · metadata · allowed-tools · a-z · scripts/
内容校验值 -> 07b2e178c075
当前原文的自动摘译,尚未人工审校。
目录结构
技能是一个至少包含一个
SKILL.md文件的目录:技能.md 格式
SKILL.md文件必须包含 YAML frontmatter,后跟 Markdown 内容。前题
字段 · 必填 · 限制
name· 是 · 最多 64 个字符。仅限小写字母、数字和连字符。不得以连字符开头或结尾。description· 是 · 最多 1024 个字符。非空。描述该技能的作用以及何时使用它。license· 否 · 许可证名称或对捆绑许可证文件的引用。compatibility· 否 · 最多 500 个字符。表示环境要求(目标产品、系统包、网络访问等)。正文内容
frontmatter 之后的 Markdown 正文包含技能说明。没有格式限制。写下任何有助于代理有效执行任务的内容。推荐部分: 分步说明 输入和输出示例 常见边缘情况
脚本/
包含代理可以运行的可执行代码。脚本应该: 是独立的或清楚地记录依赖关系 包含有用的错误消息 妥善处理边缘情况 支持的语言取决于代理实现。常见选项包括 Python、Bash 和 JavaScript。