Agent Skill 学习文档

Skill 是什么

一个 Skill 通常是一个文件夹，核心是 SKILL.md：开头的 YAML frontmatter 写名称和“什么时候该用”，正文写步骤、规范和可调用的脚本。Agent 先只读 frontmatter，判断任务相关时才加载正文。

---
name: my-skill
description: 什么时候该用这个 Skill（Agent 靠这一句决定是否加载）
---

# My Skill

1. 先做什么
2. 再做什么，必要时运行 scripts/xxx.py
3. 交付前检查什么

安装到 Agent

1. 在 Skill 目录 打开条目，复制安装命令或打开 GitHub 源。
2. 把整个 Skill 文件夹（含 SKILL.md 和它引用的脚本）放进 Agent 的 skills 目录；例如 Claude Code 使用 ~/.claude/skills/<skill 名>/ 或项目内 .claude/skills/。其他工具的目录和触发方式不同，以其官方文档为准。
3. 用一个它本应处理的任务试一下，确认 Agent 确实加载了 Skill（很多 Agent 会在回复里提到使用了哪个 Skill）。

没有 Agent？用免费模型 API 直接用 Skill

最简单的办法就是 FreeLLM 实测用的办法：把 SKILL.md 全文当作 system prompt，把任务当作 user 消息，调用任意 OpenAI 兼容的免费接口。这样拿到的是“按 Skill 说明给出的方案、代码和步骤”，但模型不会替你执行 Skill 里的脚本。

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(base_url="https://api-inference.modelscope.cn/v1", api_key=os.environ["MODELSCOPE_API_KEY"])
skill_md = Path("SKILL.md").read_text(encoding="utf-8")  # 想用的 Skill 原文

resp = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4.1-Flash",
    messages=[
        {"role": "system", "content": "请严格遵循下面的 Skill 完成任务。\n\n" + skill_md},
        {"role": "user", "content": "你的真实任务……"},
    ],
    temperature=0.2,
)
print(resp.choices[0].message.content)

示例使用本轮实测的第一个模型（魔搭 ModelScope deepseek-ai/DeepSeek-V4.1-Flash）；免费额度、速率与可用性会变化，请先看 免费模型实测榜。

读懂 Skill 实测

• 每个 Skill 只配一个固定的真实任务，检查项是确定性的：必须出现的步骤或字段、Python 代码能否被 ast 解析、JS 能否通过 node --check、HTML / YAML 能否解析。
• 结果分为 通过 / 部分通过 / 未通过 / 调用失败；“调用失败”说明没有拿到可评分的输出，不代表 Skill 本身不好用。
• 这是任务级测试，不等同在原仓库里端到端跑通；原链路验收见各 Skill 卡片里的测试记录。

本轮实测中真实出现过的调用失败类型：

• 限流 HTTP 429：68 次
• 单次调用超时被中止：36 次
• 空输出（思考耗尽 max_tokens）：5 次

查看全部实测例子 →

自己复现一次

export MODELSCOPE_API_KEY=...   # 只放在本地环境变量里，不要写进代码或提交
python scripts/eval_skills.py --only obra-brainstorming --models modelscope --out /tmp/skill-eval
cat /tmp/skill-eval/skills-latest.json

仓库维护者也可以把改动推到 skill-eval/** 分支，由 GitHub Actions 使用仓库 Secrets 运行全部 Skill，结果会提交到 data/evaluations/skills-latest.json，并作为 artifact 上传。