LLM之Agent（四十五）｜SKILL.md如何编写才是真正有效的 AI Agent Skills
如果你的 Skill 没有触发，问题几乎从来不在指令，而在 description。这是大多数人都会踩的坑。
你写好了一个 SKILL.md，把它放到正确的目录，让 Agent 使用——结果什么都没发生。
你开始怀疑：
- 是不是指令写错了？
- 于是重写 instructions
- 还是不行
但真正的问题，从来不在你写的内容，而在最上面的两行：
👉 Agent 用来判断“是否触发 Skill”的那两行（name + description）
一、什么是 Agent Skill？
Skill 不是插件，也不是你接入 API 的脚本。
可以把它理解为：
👉 一份写给 AI 的“工作手册”或“入职指南”
你不需要在每一次对话中重复解释流程，而是把这些内容写进 Skill，当用户请求匹配时，Agent 自动使用。
二、Skill 的结构
一个 Skill 本质上只是一个文件夹：
your-skill-name/
├── SKILL.md # 必需：指令 + 元数据
├── scripts/ # 可选：可执行代码
├── references/ # 可选：文档（按需加载）
└── assets/ # 可选：模板、图片等资源 👉 唯一必须的文件是：SKILL.md
为什么 SKILL.md 很重要？
SKILL.md 是一个开放标准，由 Anthropic 在 2025 年 12 月发布。
它目前被多个平台支持：
- Claude Code
- OpenAI Codex
- OpenClaw
需要注意的是：
👉 标准是统一的，但各平台的实现略有不同
（例如：上下文处理、工具权限、调用方式等）
三、Skill 放在哪里？
不同平台的加载路径不同，而且路径决定了 Skill 的作用范围。
Claude Code
~/.claude/skills/ # 个人级（全局可用）
.claude/skills/ # 项目级（可随 git 共享）
OpenAI Codex
~/.codex/skills/ # 用户级
.codex/skills/ # 仓库级
OpenClaw
全局目录
每个 Agent 独立 workspace👉 当同名 Skill 冲突时：
项目级 > 个人级
三层加载系统（核心机制）
这是理解 Skill 的关键。
Skill 使用一种“渐进加载”的机制：
Level 1：Metadata（始终加载）
在会话开始时，Agent 只读取：
- name
- description
👉 每个 Skill 约 100 tokens
👉 用途：告诉 Agent：有哪些 Skill，以及什么时候使用
Level 2：Instructions（触发时加载）
当 Agent 判断某个 Skill 相关时：
👉 才会加载完整的 SKILL.md
Level 3：References / Scripts（按需加载）
如果 Skill 中引用了其他文件：
- references 文档
- scripts 脚本
👉 只有在需要时才会加载
👉 scripts 可以直接执行，而不进入上下文
一个真实执行流程
1.会话开始→ 加载所有 Skill 的 name + description
2.用户请求：“Can you write a README for this project?”
→ Agent 判断触发 readme-writer/SKILL.md
3.SKILL.md如果引用 style.md
→ 再加载 references/style.md
4.SKILL.md如果有脚本
→ 执行 scripts/validate.sh👉 关键结论：
你可以安装很多 Skill，但不会产生上下文负担
四、Skills vs Slash Commands
Skill 有两种调用方式：
① 自动触发（Implicit Invocation）
用户自然表达需求，Agent 根据 description 判断是否使用 Skill
② 显式调用（Explicit Invocation）
在 Claude Code，你可以直接用 /skill-name 调用，或者只描述你想要的内容，Claude 会自动激活相应技能：
/readme-writer在 Codex CLI，你可以提到带有 $ 前缀的技能，或者使用 /skills 选择器：
$readme-writer document this project👉 即使支持显式调用：
description 依然至关重要，因为它决定自动触发
五、最常见的错误
description 不是写给人看的，而是写给 Agent 的触发条件。
有效的结构是：
[What the skill does] + [When to use it, with specific trigger phrases]错误示例
description: Helps with documents.仍然不够好的示例
description: Creates sophisticated multi-page documentation with advanced formatting.👉 只说明“做什么”，没有说明“什么时候用”
正确示例
description: Creates and writes professional README.md files for software projects. Use when user asks to "write a README", "create a readme", "document this project", "generate project documentation", or "help me write a README.md".👉 核心结构：
[做什么] + [什么时候用（触发语句）]
规范要求（agentskills.io）
1）name
- 小写字母、数字、连字符
- ≤64字符
- 不能以 - 开头或结尾
- 不能连续使用 --
2）description
- ≤1024字符
- 必须包含：
- 使用场景
- 功能
3）文件命名必须是SKILL.md
（大小写敏感）
⚠️ 注意
- 不要在 frontmatter 中使用 < 或 >
- 可能引入非预期指令
Skill 1：README Writer
这是一个非常实用的入门 Skill。
Setup
mkdir -p ~/.claude/skills/readme-writerSKILL.md
---
name: readme-writer
description: Creates and writes professional README.md files for software projects.
Use when user asks to "write a README", "create a readme", "document this project",
"generate project documentation", or "help me write a README.md". Works from a
project description, existing code, or both.
---
# README Writer
## Overview
Generate a complete, professional README.md file and write it to disk. The output
should be clear enough for a first-time contributor to understand the project,
set it up locally, and start contributing.
## Step 1: Gather project context
Look for context in the codebase before asking the user:
```bash
ls -la
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || \
cat go.mod 2>/dev/null || echo "No manifest found"
ls .env.example .env.sample 2>/dev/null || echo "No env example found"
```
Gather:
- What does this project do? (1-2 sentence summary)
- What language and main frameworks does it use?
- How do you install and run it?
- Are there environment variables needed?
- Is there a LICENSE file?
## Step 2: Write the README
Use this structure. Only include sections that are relevant. Do not add empty sections.
```
# Project Name
One clear sentence describing what this project does and who it is for.
## Features
- Feature one (be specific)
- Feature two
## Prerequisites
List what needs to be installed. Include version requirements if important.
## Installation
Step-by-step setup. Every command must be copy-pasteable.
```bash
git clone https://github.com/username/project
cd project
npm install
```
## Configuration
If the project needs environment variables, show an example:
```bash
cp .env.example .env
```
Then explain each variable the user needs to set manually.
## Usage
Show the most common use case first.
```bash
npm run dev
```
## License
[MIT](LICENSE)
```
## Step 3: Write the file to disk
Once the content is ready, write it:
```bash
cat > README.md << 'EOF'
[full readme content]
EOF
```
Confirm it was written:
```bash
echo "README.md written: $(wc -l < README.md) lines"
```
## Step 4: Quality check
Before finishing, verify:
- [ ] No placeholder text like "[your description here]" remains
- [ ] Every command in the Installation section is accurate for this project
- [ ] Prerequisites match what the project actually needs
- [ ] License section matches the LICENSE file if one exists
```使用方式
Can you write a README for this project?Skill 2：Git Commit Generator
Setup
mkdir -p ~/.claude/skills/git-commit-writerSKILL.md
---
name: git-commit-writer
description: Generates standardized git commit messages following conventional commits spec.
Use when user asks to "write a commit message", "help me commit", "summarize my changes",
"what should my commit say", or "draft a commit". Analyzes staged diffs and change
descriptions to produce type(scope): description format messages.
---
# Git Commit Message Writer
## Format
```
type(scope): short description
[optional body]
[optional footer]
```
Allowed types: feat, fix, docs, style, refactor, test, chore, perf, ci, build
## Instructions
### Step 1: Get the diff
```bash
git diff --staged
```
If nothing is staged:
```bash
git diff HEAD
```
### Step 2: Analyze the changes
Look for:
- What files changed and what category they belong to
- Whether this adds new functionality (feat), fixes a bug (fix), or updates docs/config/tests
- The scope: which module, component, or area is affected
### Step 3: Write the message
- Keep the subject line under 72 characters
- Use imperative mood: "add feature" not "added feature"
- Do not end the subject line with a period
- Add a body if the change needs more context than the subject allows
### Quality check
- [ ] Type is one of the allowed types
- [ ] Subject line is under 72 characters
- [ ] Imperative mood is used
- [ ] Scope is specific enough to be useful
## Examples
```
feat(auth): add OAuth2 login with Google
Implements Google OAuth2 flow using the existing session management
system. Users can now sign in with their Google account.
Closes #142
```
```
fix(api): handle null response from payment provider
```
```
docs(readme): update local setup instructions for Node 22
```
```Skill 3：Code Reviewer
关键点：👉 把复杂内容拆到 references/
mkdir -p ~/.claude/skills/code-reviewer/referencesSKILL.md
---
name: code-reviewer
description: Conducts structured code reviews with categorized feedback. Use when user asks
to "review this code", "check my PR", "look over this function", or "give me feedback on
this implementation". Produces structured output with blocking issues separate from suggestions.
---
# Code Reviewer
## Review Process
### Step 1: Understand context
Before reviewing, establish:
- What is this code supposed to do?
- What language and framework is it using?
- Is this a new feature, a bug fix, or a refactor?
### Step 2: Run the review
For detailed review criteria by category, see [references/criteria.md](references/criteria.md).
Work through each category in order. Do not skip categories even if they seem unlikely to have issues.
### Step 3: Structure the output
```
## Summary
[2-3 sentence overview and overall assessment]
## Blocking Issues
[Issues that must be fixed: security vulnerabilities, logic errors, data loss risks.
If none, write "None found."]
## Suggestions
[Non-blocking improvements numbered. Include where, why, and how to fix each.]
## Positive Notes
[What the code does well. Always include at least one.]
```
```references/criteria.md
# Review Criteria
## Security (Check First)
- SQL injection: are user inputs parameterized?
- XSS: is output properly escaped before rendering?
- Auth checks: are protected routes actually protected?
- Secrets: are API keys or credentials hardcoded anywhere?
- Input validation: is validation happening server-side?
## Correctness
- Does the logic match the stated intent?
- Are edge cases handled: empty arrays, null values, zero, negative numbers?
- Are error states surfaced correctly?
- Are async operations awaited properly?
## Readability
- Can a new team member understand this in 5 minutes?
- Are variable and function names descriptive?
- Are functions doing one thing or multiple things?
## Performance
- Are there obvious N+1 query patterns?
- Are expensive operations inside loops that could be outside?
## Tests
- Are there tests for the new behavior?
- Are edge cases tested, not just the happy path?SKILL.md 内容保持在 40 行以下。详细标准存储在 references/criteria.md 中，仅在评审进行时加载。这样可以保持 2 级的精简，而 3 级时智能体仍能获得所需的一切。
Skill 4：Sprint Planner（MCP）
-
核心能力
-
获取 Linear 数据
-
分析 backlog
-
计算容量
-
创建 Sprint
-
-
流程
-
拉数据
-
分析 capacity
-
排优先级
-
输出方案
-
等确认
-
执行
-
Setup
mkdir -p ~/.claude/skills/linear-sprint-planner/referencesSKILL.md
---
name: linear-sprint-planner
description: Automates Linear sprint planning including cycle creation, backlog triage,
and task assignment. Use when user says "plan the sprint", "set up the next cycle",
"help me prioritize the backlog", or "create sprint tasks in Linear". Requires Linear
MCP server to be connected.
metadata:
mcp-server: linear
version: 1.0.0
---
# Linear Sprint Planner
## Prerequisites
Verify the Linear MCP server is connected. If not available, tell the user to connect
it in their MCP settings before continuing.
## Process
### Step 1: Gather current state
Fetch from Linear in sequence:
1. Current active cycle and completion percentage
2. All backlog issues (status: Backlog or Todo, not assigned to any cycle)
3. Team members and current workload
4. Any issues marked high priority
See [references/linear-api.md](references/linear-api.md) for pagination and rate limit handling.
### Step 2: Analyze capacity
- Count team members participating in the sprint
- Estimate points (default: 10 per person per week unless historical velocity exists)
- Subtract planned time off
Present a summary before proceeding:
Team capacity: - [N] engineers x [X] points = [Total] available - Carrying over: [X] points - Net new capacity: [X] points
### Step 3: Prioritize backlog
Sort in this order:
1. P0/P1 bugs and blockers (always include)
2. Items explicitly flagged by the user
3. Items that unblock other teams
4. Features by product priority
5. Tech debt
Do not exceed capacity by more than 10% unless the user asks.
### Step 4: Present for approval
Before creating anything in Linear, show the proposed plan:
Proposed Sprint [N]: [Date Range] Capacity: [X] points Issues: - [ISSUE-123] Fix payment timeout (P0) - 3 pts - [ISSUE-456] Add CSV export (P2) - 5 pts - [ISSUE-789] Refactor auth middleware - 2 pts Total: [X] / [X] points Shall I create this cycle and assign these issues?
Always wait for confirmation before making changes.
### Step 5: Create and confirm
Once approved:
1. Create the cycle with the agreed date range
2. Add each issue to the cycle
3. Update assignments if the user specified owners
4. Return a summary with the Linear cycle link
See [references/error-handling.md](references/error-handling.md) if any API calls fail.references/linear-api.md
# Linear API Patterns
## Fetching backlog
Paginate in batches of 50. Check pageInfo.hasNextPage and use the after cursor.
Filter for: status [Backlog, Todo], cycle: null.
## Creating a cycle
Required: name, startsAt, endsAt, teamId
## Adding issues
Use issueUpdate mutation to set cycleId. Batch where possible.
## Rate limiting
On 429: wait 1 second, retry once. If it fails again, report to user and continue.references/error-handling.md
# Error Handling
## MCP connection errors
Tell the user: "Linear MCP appears to be disconnected. Please reconnect before
running sprint planning." Do not proceed.
## Missing data
Continue with available data. Note what is missing in the final summary.
## Cycle creation failure
Do not attempt to add issues. Report the error and suggest checking permissions.👉 示例触发：
Help me plan the next sprint in Linear一个重要认知
👉 Skill 不保证执行
它只是：
提高模型一致性的结构化指导
allowed-tools（可选）
allowed-tools: Read, Grep, Glob
👉 限制 Agent 行为
团队共享
.claude/skills/
Skill 不触发怎么排查？
-
description
-
路径
-
YAML
-
重启
-
显式调用
安全提醒
Skill 可能：
- 执行代码
- 访问外部服务
建议：
- 使用可信来源
- 检查 scripts/
- 不输入密钥
六、四个Skills的关联
以下是这四项技能的示意图，以及它们在复杂度谱上的位置：
从 git-commit-writer 开始。需要文件输出时，使用 readme-writer 模式。当你的技能变得太长时，像code-reviewer一样拆分。当你需要外部工具协调时，可以使用linear-sprint-planner模式。
七、allowed-tools字段
大多数人从未用过的前件字段是allowed-tools 。它限制了当技能激活时，代理可以调用哪些工具。
这对于只读技能非常有用，因为你不希望智能体误写或执行任何内容：
---
name: log-analyzer
description: Analyzes application log files to identify errors and patterns. Use when
user says "check the logs", "what errors are in my logs", or "analyze this log file".
allowed-tools: Read, Grep, Glob
---
# Log Analyzer
1. Use Glob to find log files: *.log, logs/*.log, /var/log/*.log
2. Use Grep to search for error patterns: ERROR, FATAL, Exception, Traceback
3. Group errors by type and frequency
4. Summarize with the most frequent errors first激活后，智能体无法执行 shell 命令、写文件或进行任何外部调用。
注意： allowed-tools在智能体技能规范中标记为实验性，且不同智能体实现支持不同。如今，Claude Code 对此有很好的支持。
八、与团队分享Skills
最简洁的方法是将项目技能投入到你的仓库中：
mkdir -p .claude/skills/readme-writer
# add SKILL.md, then:
git add .claude/skills/
git commit -m "Add readme-writer skill for team"
git push当队友拉取仓库时，Skills会立即开放，无需单独安装步骤。在 Codex 中，对应路径是 .codex/skills/。
九、如何debug你的Skills
9.1 查看你的description
这是最常见的问题。为了满足用户的特殊请求方式，添加了很多具体的触发词。
9.2 检查你的文件路径
# Claude Code personal skill
ls ~/.claude/skills/your-skill/SKILL.md
# Claude Code project skill
ls .claude/skills/your-skill/SKILL.md
# Codex
ls ~/.codex/skills/your-skill/SKILL.md9.3 检查YAML语法
无效的 YAML 会无声地阻止加载。第 1 行必须从---开始，另一行以--- 结束。
9.4 重新开始会话
运行会话中对Skills所做的编辑需要重启才能生效。
9.5 在debug模式下运行
claude --debug9.6 带有明确调用的测试
Use the readme-writer skill to document this project如果在明确调用时有效但不自动，说明需要更具体的触发词。
十、Skill安全性
只安装可信来源的技能。在安装任何社区Skill之前，请阅读文件夹里的每个文件，尤其是scripts/里的内容。注意指示agent拨打外呼网络电话或向外部服务发送数据的说明。
思科研究人员警告称，通过即时注入进行无声数据窃取的技能存在。安全审计扫描了数千个社区技能，发现了包括凭证盗窃和恶意软件在内的关键漏洞。Snyk 对此有专门的研究成果发表。ClawHub 有一个 VirusTotal 集成，你可以在安装前检查技能，但对于权限较宽的软件，手动审核仍然值得。
一些实用规则：
- 千万不要安装需要你把秘密粘贴到聊天里的技能；
- 安装前一定要看脚本；
- 对设置说明中进行外呼网络调用的技能保持怀疑；
- 优先选择官方来源的技能：Anthropic 或 OpenAI 的技能库，或者你自己团队的技能库
十一、总结
三个核心：
-
description 决定触发
-
三层加载决定性能
-
Skill 是指导，不是程序
十二、结尾
SKILL.md 已成为 AI Agent 的基础设施。
👉 一次编写，多平台复用
👉 能力沉淀，而不是重复提示
如果你在做 AI 编程或自动化，这套 Skill 体系，值得认真投入。
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
9
0- 0
已为社区贡献2条内容
所有评论(0)