agentskills-specification

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Skills Specification

Skill by ara.so — AI Agent Skills collection.

Agent Skills is an open format for packaging instructions, scripts, and resources that AI agents can discover and use to perform better at specific tasks. Skills are folders containing a

SKILL.md

file with structured information that agents can load to gain expertise in specific domains or tools.

由ara.so提供的Skill——AI Agent Skills集合。

Agent Skills是一种开放格式，用于打包AI Agent可发现并使用的指令、脚本和资源，以提升其在特定任务中的表现。Skills是包含

SKILL.md

文件的文件夹，该文件带有结构化信息，Agent可加载这些信息来获得特定领域或工具的专业能力。

What Agent Skills Are

Agent Skills是什么

Agent Skills provide:

Standardized format for agent capabilities via Markdown with YAML frontmatter
Discoverability through triggers and structured metadata
Portability across different AI agent platforms
Composability allowing agents to combine multiple skills

Agent Skills提供：

标准化格式：通过带有YAML前置元数据的Markdown定义Agent能力
可发现性：通过触发词和结构化元数据实现
可移植性：可在不同AI Agent平台间通用
可组合性：允许Agent组合使用多个技能

Installation

安装

Agent Skills are typically distributed as folders containing at minimum a

SKILL.md

file:

bash

undefined

Agent Skills通常以文件夹形式分发，至少包含一个

SKILL.md

文件：

bash

undefined

Clone the reference implementation

克隆参考实现

git clone https://github.com/agentskills/agentskills.git

Or see example skills

或查看示例技能

git clone https://github.com/anthropics/skills.git


Individual skills are installed by placing them in a directory that your AI agent monitors (implementation-specific).

git clone https://github.com/anthropics/skills.git


单个技能的安装方式是将其放置在AI Agent监控的目录中（具体取决于实现方式）。

SKILL.md Format

SKILL.md格式

Every Agent Skill must have a

SKILL.md

file with YAML frontmatter followed by Markdown content.

每个Agent Skill必须包含一个

SKILL.md

文件，文件开头是YAML前置元数据，后续为Markdown内容。

Basic Structure

基本结构

markdown

---
name: skill-name-in-kebab-case
description: One-line description of what this skill does
triggers:
  - natural phrase users might say
  - another trigger phrase
  - how to use this skill
---

markdown

---
name: skill-name-in-kebab-case
description: 该技能功能的单行描述
triggers:
  - 用户可能说出的自然语句
  - 另一个触发语句
  - 如何使用该技能
---

Skill Name

技能名称

Detailed documentation in Markdown format...

undefined

Markdown格式的详细文档...

undefined

Required Frontmatter Fields

必填前置元数据字段

yaml

---
name: database-query-optimizer
description: Optimize SQL queries for PostgreSQL and MySQL databases
triggers:
  - optimize my database query
  - improve SQL performance
  - analyze query execution plan
  - find slow queries
  - index suggestions
  - database performance tuning
---

Field Specifications:

```
name
```
: kebab-case identifier, descriptive and unique
```
description
```
: Single line, under 200 characters
```
triggers
```
: 6-8 natural language phrases that should activate this skill

yaml

---
name: database-query-optimizer
description: 为PostgreSQL和MySQL数据库优化SQL查询
triggers:
  - 优化我的数据库查询
  - 提升SQL性能
  - 分析查询执行计划
  - 查找慢查询
  - 索引建议
  - 数据库性能调优
---

字段说明：

```
name
```
：短横线命名格式的标识符，描述性强且唯一
```
description
```
：单行文本，不超过200个字符
```
triggers
```
：6-8个可触发该技能的自然语言语句

Optional Frontmatter Fields

可选前置元数据字段

yaml

---
name: docker-deployment
description: Deploy applications using Docker and Docker Compose
version: 1.0.0
author: Your Name
requires:
  - docker >= 20.10.0
  - docker-compose >= 2.0.0
platform:
  - linux
  - macos
triggers:
  - deploy with docker
  - create docker container
  - write dockerfile
  - docker compose setup
  - containerize application
  - build docker image
---

yaml

---
name: docker-deployment
description: 使用Docker和Docker Compose部署应用
version: 1.0.0
author: 你的名字
requires:
  - docker >= 20.10.0
  - docker-compose >= 2.0.0
platform:
  - linux
  - macos
triggers:
  - 使用Docker部署
  - 创建Docker容器
  - 编写Dockerfile
  - Docker Compose配置
  - 应用容器化
  - 构建Docker镜像
---

Creating a Complete Skill

创建完整技能

1. Start with Frontmatter

1. 编写前置元数据

yaml

---
name: fastapi-rest-api
description: Build REST APIs with FastAPI framework including async operations, validation, and documentation
triggers:
  - create fastapi endpoint
  - build rest api with fastapi
  - fastapi async route
  - add pydantic validation
  - setup fastapi project
  - fastapi dependency injection
version: 1.0.0
requires:
  - fastapi >= 0.100.0
  - pydantic >= 2.0.0
---

yaml

---
name: fastapi-rest-api
description: 使用FastAPI框架构建REST API，包括异步操作、验证和文档
triggers:
  - 创建FastAPI端点
  - 使用FastAPI构建REST API
  - FastAPI异步路由
  - 添加Pydantic验证
  - 配置FastAPI项目
  - FastAPI依赖注入
version: 1.0.0
requires:
  - fastapi >= 0.100.0
  - pydantic >= 2.0.0
---

2. Add Core Documentation

2. 添加核心文档

markdown

undefined

markdown

undefined

FastAPI REST API

Overview

概述

FastAPI is a modern, fast web framework for building APIs with Python 3.7+ based on standard Python type hints.

FastAPI是一个现代、高性能的Web框架，用于基于Python类型提示构建Python 3.7+的API。

Installation

安装

bash

pip install fastapi uvicorn[standard]

bash

pip install fastapi uvicorn[standard]

Basic Usage

基础用法

Simple Endpoint

简单端点

python

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

python

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

Run the Server

启动服务器

bash

uvicorn main:app --reload

undefined

bash

uvicorn main:app --reload

undefined

3. Include Real Code Examples

3. 包含真实代码示例

python

from fastapi import FastAPI, HTTPException, Depends
from pydantic import BaseModel, Field
from typing import List, Optional
import os

app = FastAPI(title="My API", version="1.0.0")

python

from fastapi import FastAPI, HTTPException, Depends
from pydantic import BaseModel, Field
from typing import List, Optional
import os

app = FastAPI(title="My API", version="1.0.0")

Models with validation

带验证的模型

class Item(BaseModel): name: str = Field(..., min_length=1, max_length=100) description: Optional[str] = None price: float = Field(..., gt=0) tax: Optional[float] = None

class ItemResponse(BaseModel): id: int name: str price: float

class Item(BaseModel): name: str = Field(..., min_length=1, max_length=100) description: Optional[str] = None price: float = Field(..., gt=0) tax: Optional[float] = None

class ItemResponse(BaseModel): id: int name: str price: float

Dependency injection

依赖注入

def get_api_key(api_key: str = Depends(lambda: os.getenv("API_KEY"))): if not api_key: raise HTTPException(status_code=401, detail="API key required") return api_key

def get_api_key(api_key: str = Depends(lambda: os.getenv("API_KEY"))): if not api_key: raise HTTPException(status_code=401, detail="需要API密钥") return api_key

CRUD endpoints

CRUD端点

items_db = []

@app.post("/items/", response_model=ItemResponse, status_code=201) async def create_item(item: Item, api_key: str = Depends(get_api_key)): item_dict = item.dict() item_dict["id"] = len(items_db) + 1 items_db.append(item_dict) return item_dict

@app.get("/items/", response_model=List[ItemResponse]) async def list_items(skip: int = 0, limit: int = 10): return items_db[skip : skip + limit]

@app.get("/items/{item_id}", response_model=ItemResponse) async def get_item(item_id: int): if item_id > len(items_db) or item_id < 1: raise HTTPException(status_code=404, detail="Item not found") return items_db[item_id - 1]

undefined

items_db = []

@app.get("/items/", response_model=List[ItemResponse]) async def list_items(skip: int = 0, limit: int = 10): return items_db[skip : skip + limit]

undefined

4. Add Configuration Section

4. 添加配置部分

markdown

undefined

markdown

undefined

Configuration

配置

Environment Variables

环境变量

```
API_KEY
```
: Authentication key for protected endpoints
```
DATABASE_URL
```
: Connection string for database
```
LOG_LEVEL
```
: Logging level (DEBUG, INFO, WARNING, ERROR)

```
API_KEY
```
：受保护端点的认证密钥
```
DATABASE_URL
```
：数据库连接字符串
```
LOG_LEVEL
```
：日志级别（DEBUG, INFO, WARNING, ERROR）

CORS Setup

CORS配置

python

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

undefined

python

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

undefined

5. Include Common Patterns

5. 包含常见模式

markdown

undefined

markdown

undefined

Common Patterns

常见模式

Background Tasks

后台任务

python

from fastapi import BackgroundTasks

def write_log(message: str):
    with open("log.txt", "a") as f:
        f.write(f"{message}\n")

@app.post("/send-notification/{email}")
async def send_notification(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, f"Notification sent to {email}")
    return {"message": "Notification sent"}

python

from fastapi import BackgroundTasks

def write_log(message: str):
    with open("log.txt", "a") as f:
        f.write(f"{message}\n")

@app.post("/send-notification/{email}")
async def send_notification(email: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, f"已向{email}发送通知")
    return {"message": "通知已发送"}

Error Handling

错误处理

python

from fastapi import Request
from fastapi.responses import JSONResponse

@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
    return JSONResponse(
        status_code=400,
        content={"message": str(exc)},
    )

undefined

python

from fastapi import Request
from fastapi.responses import JSONResponse

@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
    return JSONResponse(
        status_code=400,
        content={"message": str(exc)},
    )

undefined

6. Add Troubleshooting

6. 添加故障排除

markdown

undefined

markdown

undefined

Troubleshooting

故障排除

Port Already in Use

端口已被占用

bash

undefined

bash

undefined

Change the port

更换端口

uvicorn main:app --port 8001

undefined

uvicorn main:app --port 8001

undefined

Import Errors

导入错误

Ensure all dependencies are installed:

bash

pip install -r requirements.txt

确保已安装所有依赖：

bash

pip install -r requirements.txt

Auto-reload Not Working

自动重载不生效

Use the

--reload

flag and ensure you're editing the correct file:

bash

uvicorn main:app --reload --reload-dir ./app

undefined

使用

--reload

标志并确保编辑的是正确文件：

bash

uvicorn main:app --reload --reload-dir ./app

undefined

Skills Directory Structure

技能目录结构

my-skill/
├── SKILL.md           # Required: Main skill documentation
├── resources/         # Optional: Additional files
│   ├── templates/
│   ├── examples/
│   └── scripts/
└── README.md          # Optional: Human-readable documentation

my-skill/
├── SKILL.md           # 必填：主技能文档
├── resources/         # 可选：附加文件
│   ├── templates/
│   ├── examples/
│   └── scripts/
└── README.md          # 可选：面向人类阅读的文档

Python SDK Usage

Python SDK使用

If there's a Python SDK for working with Agent Skills:

python

from agentskills import Skill, SkillRegistry

如果有用于操作Agent Skills的Python SDK：

python

from agentskills import Skill, SkillRegistry

Load a skill

加载技能

skill = Skill.from_file("path/to/SKILL.md")

Access metadata

访问元数据

print(skill.name) print(skill.description) print(skill.triggers)

Parse content

解析内容

content = skill.parse_markdown()

Registry for managing multiple skills

用于管理多个技能的注册表

registry = SkillRegistry() registry.discover("./skills") # Auto-discover skills in directory

registry = SkillRegistry() registry.discover("./skills") # 自动发现目录中的技能

Find skills by trigger

通过触发词查找技能

matched_skills = registry.match_trigger("create fastapi endpoint")

Load skill content

加载技能内容

skill_content = registry.get_skill("fastapi-rest-api")

undefined

skill_content = registry.get_skill("fastapi-rest-api")

undefined

Best Practices

最佳实践

1. Descriptive Naming

1. 描述性命名

Use kebab-case names that clearly identify the project or capability:

✅
```
postgresql-database-optimization
```
✅
```
react-component-library
```
❌
```
database
```
(too generic)
❌
```
myskill
```
(not descriptive)

使用短横线命名格式，清晰标识项目或能力：

✅
```
postgresql-database-optimization
```
✅
```
react-component-library
```
❌
```
database
```
（过于通用）
❌
```
myskill
```
（缺乏描述性）

2. Effective Triggers

2. 有效的触发词

Write triggers as natural phrases users would say:

yaml

triggers:
  - optimize postgres queries  # ✅ Specific and natural
  - improve database performance  # ✅ Common phrasing
  - db perf  # ❌ Too abbreviated
  - use this skill  # ❌ Too generic

将触发词写为用户会说的自然语句：

yaml

triggers:
  - optimize postgres queries  # ✅ 具体且自然
  - improve database performance  # ✅ 常用表述
  - db perf  # ❌ 过于简略
  - use this skill  # ❌ 过于通用

3. Real, Working Code

3. 真实可运行的代码

Always provide complete, executable examples:

python

undefined

始终提供完整可执行的示例：

python

undefined

✅ Complete example with imports

✅ 包含导入语句的完整示例

import os from typing import Optional

def connect_db(db_url: Optional[str] = None): url = db_url or os.getenv("DATABASE_URL") if not url: raise ValueError("DATABASE_URL not set") return connect(url)

undefined

import os from typing import Optional

def connect_db(db_url: Optional[str] = None): url = db_url or os.getenv("DATABASE_URL") if not url: raise ValueError("未设置DATABASE_URL") return connect(url)

undefined

4. Environment Variables for Secrets

4. 使用环境变量存储密钥

Never include actual secrets:

python

undefined

切勿包含真实密钥：

python

undefined

✅ Use environment variables

✅ 使用环境变量

api_key = os.getenv("OPENAI_API_KEY")

❌ Never hardcode

❌ 切勿硬编码

api_key = "sk-1234567890abcdef"

undefined

api_key = "sk-1234567890abcdef"

undefined

5. Focus on Practical Usage

5. 注重实际使用

Prioritize common use cases over comprehensive API documentation:

Installation and setup
Most frequently used features
Common patterns and workflows
Troubleshooting actual problems

优先考虑常见用例而非全面的API文档：

安装与配置
最常用的功能
常见模式与工作流
实际问题的故障排除

Skill Discovery

技能发现

Agents discover skills through:

Directory scanning: Looking for
```
SKILL.md
```
files
Trigger matching: Comparing user input to trigger phrases
Context relevance: Using skill metadata to determine applicability

Agent通过以下方式发现技能：

目录扫描：查找
```
SKILL.md
```
文件
触发词匹配：将用户输入与触发语句对比
上下文相关性：使用技能元数据判断适用性

Validation

验证

Basic validation checklist:

YAML frontmatter is valid
Required fields present:
```
name
```
,
```
description
```
,
```
triggers
```
Name is in kebab-case
6-8 trigger phrases provided
Code examples are in correct language
No hardcoded secrets
Markdown renders correctly

基础验证清单：

YAML前置元数据有效
必填字段齐全：
```
name
```
、
```
description
```
、
```
triggers
```
名称为短横线命名格式
提供了6-8个触发语句
代码示例语言正确
无硬编码密钥
Markdown渲染正常

Resources

资源

Specification: https://agentskills.io/specification
Example Skills: https://github.com/anthropics/skills
Documentation: https://agentskills.io
Community: https://discord.gg/MKPE9g8aUy

规范文档：https://agentskills.io/specification
示例技能：https://github.com/anthropics/skills
官方文档：https://agentskills.io
社区：https://discord.gg/MKPE9g8aUy

Common Issues

常见问题

Frontmatter Not Parsing

前置元数据无法解析

Ensure three dashes on their own lines:

markdown

---
name: my-skill
---

确保前后有单独成行的三个短横线：

markdown

---
name: my-skill
---

Triggers Not Matching

触发词不匹配

Make triggers conversational and specific to the domain:

yaml

triggers:
  - "create a react component"  # Better than "react"
  - "setup webpack configuration"  # Better than "webpack"

将触发词写得更具对话性且针对特定领域：

yaml

triggers:
  - "创建React组件"  # 比"react"更好
  - "配置Webpack"  # 比"webpack"更好

Skills Not Loading

技能无法加载

Check file structure and ensure

SKILL.md

is at the root of the skill directory.

检查文件结构，确保

SKILL.md