简单说：相当于说明文档

Agent 技能（Agent Skills） 是一种轻量、开放的格式，用于通过专业知识与工作流来扩展 AI 智能体的能力。

核心来说：一个技能就是一个包含 SKILL.md 文件的文件夹。该文件包含元数据（至少包含名称和描述）和指导智能体如何执行特定任务的指令。技能还可以打包脚本、模板和参考资料。

简单理解：skill 是一种可移植、可版本管理的程序包，用于教会智能体如何完成特定领域的任务。

• ClaudeCode skill要求放在：".claude/skills"(项目级)、"~/.claude/skills/"(全局) （对话框内输入"/"可以选择指令及skill，其他编辑器如kiro等基本也是）
• openCode放在".opencode/skills"，兼容.claude/skills等目录
• kiro：.kiro/skills/、~/.kiro/skills/
• Cursor：目录如下，Cursor 也会加载 Claude、Codex 的技能目录：.claude/skills/、.codex/skills/、~/.claude/skills/、~/.codex/skills/。

位置	作用域
.agents/skills/	项目级
.cursor/skills/	项目级
~/.cursor/skills/	用户级（全局）

skills目录下是一堆skill文件夹，每个文件夹是一个skill，如下每个skill必须有SKILL.md，其他可选，也可以自定义目录

skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
└── assets/           # Optional: templates, resources

SKILL.md中name必须和skill文件夹的名称相同，元数据中name和description必须，其他字段可选（参考下面skill开发中的文档）

SKILL.md 文件包含 YAML 前置信息 和 Markdown 指令，YAML 前置信息其他字段参考skill开发文档，Markdown 指令内容自定义，主要可以说明skill作用、使用步骤、输入、输出、边界问题等

---
name: skill-name
description: A description of what this skill does and when to use it.
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

按需加载：

Skill使用渐进式加载机制来高效管理上下文：

1. 发现（Discovery）启动时，智能体只加载每个技能的名称和描述，仅用于判断该技能是否可能相关。

2. 激活（Activation）当任务匹配某个技能的描述时，智能体才会把完整的 SKILL.md 指令加载到上下文。

3. 执行（Execution）智能体按照指令执行，可按需加载引用文件或执行打包的代码。

这种机制让智能体保持快速响应，同时能在需要时访问更多上下文。

Reference：存放说明文档，条件触发（如财务手册只有部分条件满足时才用到，因此每次用到会议总结skill都带过去会很浪费token，所以需要时再触发，按需中的按需加载）

Script：存放agent可以执行的代码，运行脚本（脚本代码不会携带给LLM，LLM只会告诉agent需要执行，由agent执行后把结果给LLM）

Asset：官方说放置静态资源，如模板、图片资源、数据文件等

可以安装Claude Code、Codex、Cursor、OpenCode等来使用skills：

下载skills：https://skill0.io/zh

openCode安装：https://opencode.ai/docs/zh-cn

//OpenCode 客户端支持在对话框中输入 / 、@ 等执行系统命令，比如：
@：引用项目中的文件、文件夹等内容，作为对话上下文
/init ：初始化创建一个 AGENTS.md ，这个文件对 OpenCode 来说非常重要，后面章节详细介绍；
/review ：review 异动的文件代码，默认是 review 未提交的代码；
/new ：创建一个新会话
/open ：搜索并打开一个文件
/terminal：显示或隐藏一个终端
/model：选择一个模型
/mcp：开启或关闭 MCP
/agent：选择一个 Agent 执行（build、plan）
/undo、/compact等命令

skill开发参考：

1. 官网文档https://agentskills.io/specification
2. 电子书：https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf?hsLang=en

如下开发的skill示例：

注意：开发skill时，可以下载帮助创建skill的魔法skill，如skill-creator（官方skill库中）

什么场景可以被定义为skill：正确性可以被提前定义，后面可以重复使用

skill案例：

---
name: weekly-report-generator
description: 自动生成项目周报，从git提交、issue、todo文件和用户输入记录中提取信息，生成专业的 HTML|PDF 周报。
---

# 指令:
你是一个项目周报生成助手。你的任务是从多种数据源收集本周的项目进展，并生成结构化的周报。

## 核心流程

1. **收集数据**
  -询问用户本周的时间范围(默认:本周一到周日)
  -读取项目gitlog，提取本周的提交记录
  -检查是否有issue或todo文件，提取相关进展检查项目目录中是否有 problems.md/json、growth.md/json、knowledge.md/json 文件
  -如果项目中没有上述文件，询问用户是否有额外需要添加的内容

2.**处理数据**
  -使用 scripts/git-analyzer.py分析 git 提交，提取关键信息
  -使用 scripts/todo-parser.py 解析 todo/issue,整理完成情况
  -使用 scripts/user-content-parser.py 解析项目中的用户内容文件(problems、growth、knowledge)，使用scripts/data-aggregator.py 聚合所有数据，支持 --project-dir 参数指定项目目录参考 references/data-extraction.md 了解详细的数据提取方法

3.**组织周报结构**
  -参考references/report-structure.md 了解周报的标准结构将数据组织成以下模块:
    -数据统计(提交数、参与人数、完成事项等)
    -本周进展(功能开发、问题修复、技术改进)
    -本周遇到的问题
    -本周个人成长
    -相关知识分享
    -下周计划
    -风险与问题

4.**生成报告**
  -参考 references/template-filling.md 了解模板填充逻辑使用 assets/report-template.html 作为模板
  -将结构化数据填充到模板中
  -生成HTML格式的周报文件:weekly-report-YYYY-MM-DD.html
  -使用 scripts/html-to-pdf.py 将 HTML 转换为 PDF
  -生成PDF 格式的周报文件:weekly-report-YYYY-MM-DD.pdf

## 周报内容说明

用户需要提供以下内容(支持三种方式):

**方式一:在项目中提供文件(推荐)**
-**本周遇到的问题**:在项目根目录创建 problems.md或 problems.json文件
-**本周个人成长**:在项目根目录创建 growth.md或 growth.json文件
-**相关知识分享**:在项目根目录创建 ‘knowledge.md 或 ‘knowledge.json’文件

JSON 格式需符合user-input.json 中的结构定义。Markdown 格式需包含相应的标题和内容。

**方式二:通过 user-input.json 文件提供**
-在 user-input.json 中义 problems、growth、knowledge 字段

**方式三:对话提供**
-如果项目中没有提供文件，按规则询问用户输入

内容说明:
-**本周遇到的问题**:开发过程中遇到的技术难题、阻塞问题等，包含问题描述、类型、解决方案、经验教训
-**本周个人成长**:学到的技术、能力提升、经验总结，包含类别、内容、影响
-**相关知识分享**:值得记录的技术知识点、最佳实践、学习资源，包含标题、内容、资源链接

## 使用说明
用户可以直接说:"帮我生成本周的周报"，或者提供具体的时间范围。

## 注意事项
  -如果项目不是 git 仓库，跳过 git log 分析
  -如果没有 issue 或 todo 文件，提醒用户手动输入关键进展
  -需要安装 Chrome 或使用浏览器手动生成 PDF
  -同时输出 HTML 和 PDF 两种格式