大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



本文是系统学习 Agent Skills（以 Anthropic/Claude Skills 体系为主，结合 opencode 实操）后的完整笔记整理：

• 整体思路围绕三个核心目标展开：一套可复用的理解框架（渐进式披露/三层结构） + 一套可落地的使用路径（下载安装到能用） + 一套最小可行的“造 Skill”模板。
• 适合读者：希望把 AI 从“会聊天”提升到“能按 SOP 干活”的同学；以及希望把个人/团队流程沉淀成可复用能力包的开发者。

• 适用场景：
  • 在工作与学习中，如果经常遇到重复性很强的任务（如写周报、生成文档、整理资料、批量处理文件或跑固定分析流程）；
  • 相比每次都临时“手搓 Prompt”，更希望 AI 能稳定按流程做事；
  • 目标是把“个人经验、流程或规范”沉淀为 可复用能力包，实现即拿即用。
• 核心结论：
  • Skills 可以理解成 AI 的“能力包/岗位说明书”：把元数据 + 指令 SOP + 资源/脚本打包，让 AI 按需加载，在特定任务上更稳更专业。
  • Skills 的关键不是“写更长的 Prompt”，而是用结构化的指令约束 AI 的思考路径，必要时用脚本/资源把确定性步骤做实。
  • 最好用的 Skills 往往具备：

 
  
    
    
 
     
可触发（名字/描述清晰）
 
     
可执行（步骤可落地）
 
     
可校验（有验证/输出规范）
 
     
可复用（输入输出稳定）
 
    
 
最短上手路径： 

• 下载/安装一个支持 Skills 的 Agent（本文以 opencode 路线示例）
• 把现成 skill 文件夹拷到 Agent 识别目录
• 启动 Agent，问它“有哪些 skills”，再用一句话触发

常用命令/操作：

• Claude Code（官方仓库给出的方式）：

 
  
    
    
 
     
/plugin marketplace add anthropics/skills
 
    
 
opencode： 
     
 
      
打开：opencode
 
      
连接模型：/connect
 
      
切换模型：/models
 
     
 
 
避坑提醒： 

• 路径尽量英文，避免中文/空格在某些工具链里出问题。
• Skill 的 name 通常要与文件夹名一致（至少要保持唯一、可识别）。
• 只靠“长 Prompt”会漂；要加上输入/输出规范与验证步骤。

---

1. 理解 Skills 的本质：它到底和 Prompt、Tool、Agent 有何区别
2. 掌握一个 Skill 的典型结构：SKILL.md、scripts/、references/、assets/
3. 能把一个“重复工作”做成第一个可复用 Skill（最小可行版本）

---

1.1 Skills 的官方定义（来自 anthropics/skills）

Anthropic 官方仓库对 Skills 的描述是：

• Skills 是一些文件夹，里面包含 instructions（指令）、可能的 scripts（脚本）、以及 resources（资源）；
• Claude 会在需要时动态加载这些内容，以提高在特定任务上的表现；
• 技能的目标是让 Claude 在“专业任务”上更稳定、更可复用。

参考：GitHub anthropics/skills 仓库 README（Skills / About This Repository）

1.2 一个好用的类比：能力包/岗位说明书

Skills 可以理解成 AI 的“能力包/岗位说明书”：把元数据 + 指令 SOP + 资源/脚本打包，让 AI 按需加载，在特定任务上更稳更专业。

1.3 核心术语对比（建议表格）

---

2.1 “渐进式披露”：Skills 背后的设计哲学

Skills 的设计哲学是“渐进式披露”，让 AI 像人类专家一样按需调动知识与流程。

2.2 Skill 的三层结构：元数据层 / 指令层 / 资源层

一个 Skill 的典型结构包括：

1. 便 元数据层（识别与触发）
   • 相当于 Skill 的“名片”：name + description
   • 目的：让 Agent 的意图识别更容易命中所需技能
2.  指令层（思考与规划）
   • 相当于“专家 SOP 注入”：告诉 AI 先做什么、后做什么、如何判断成功、输出是什么
   • 这是让 AI 从“泛化回答”切换到“按行业**实践做事”的关键
3.  资源层（执行与校验）
   • 资源可以是脚本/模板/参考文档
   • 目的：把确定性动作交给程序，把关键规范放在可引用的外部记忆里，提高可靠性
     
     
     

说明：官方仓库给了 Claude Code 的安装方式；我的笔记以 opencode 为例，演示“安装 Agent -> 连接模型 -> 放入 skills -> 触发使用”的完整链路。

3.1 环境准备

• 系统：Windows / macOS 均可
• Agent：opencode（示例）或 Claude Code（官方路径）
  https://opencode.ai/download
  https://opencode.ai/docs
  
  
  
  
  
• 模型：可用 Anthropic / 国内模型（如智谱等，取决于你的工具支持）

3.2 安装 Agent（opencode 示例）

• Tips：安装后记得让环境变量生效（如重启终端/重新加载配置）

3.3 准备模型 API_KEY 并连接模型

以“阿里云”为例：

1. 去开放平台创建 API_KEY
   
   
   
   
2. 在 opencode 里点击设置
   
   
   
   
3. 搜索对应提供商，输入 key，选择模型

3.4 下载 Skills（从哪里找现成技能）

我的笔记里给了很多来源，这里整理成“收藏夹”级别的清单：

• Anthropic 官方仓库：https://github.com/anthropics/skills
• 社群/市场：https://skillsmp.com/zh、https://skillstore.io/zh-hans
• 合集：
  • https://github.com/ComposioHQ/awesome-claude-skills
  • https://github.com/JackyST0/awesome-agent-skills
  • https://agent-skills.md/（大集合）

建议：优先从“官方/高星/维护频繁”的仓库挑选，并自己做一层“可用性验证”。

3.5 使用 Skills（最关键：放到哪里 + 怎么触发）

3.5.1 项目级使用（推荐：与项目绑定）

我的笔记给了一个清晰结构：

• 在项目根目录下创建：.opencode/skills/（或 .opencode/skill/ 也可）
• 把下载好的 skill 文件夹拷贝进去
• 在项目目录打开 opencode
• 问它“有哪些 skills”，再提具体需求让它执行

结合官方仓库与参考文章，一个典型 skill 结构如下：

skill-name/ SKILL.md # 核心说明（必须） scripts/ # 可执行脚本（可选） references/ # 参考资料/规范/流程（可选） assets/ # 模板/静态资源（可选） 

4.1 SKILL.md：最小必需品

官方仓库强调：一个基础 skill 就是“文件夹 + SKILL.md”。

SKILL.md 主要包含：

• YAML frontmatter：
  • name：唯一标识（通常小写+连字符）
  • description：清晰描述“做什么/什么时候用”
• Markdown 正文：
  • 指令（流程、规则、输出要求）
  • Examples（触发示例）
  • Guidelines（边界、注意事项）

官方还指出：仓库里很多 skills 是 Apache 2.0，但 docx/pdf/pptx/xlsx 属于 source-available（可参考但不是开源许可）。

4.2 scripts / references：把“确定性”和“规范性”外置

• scripts：把可确定执行的事情交给脚本（解析、格式化、生成文件、批量处理）
• references：把规则/模板外置（如报告结构、抽取规则、对照表、品牌规范）

我的笔记里的“周报生成器 Skill”就是很典型的组合：

• 指令里定义“收集数据 -> 处理数据 -> 组织结构 -> 生成报告”的 SOP
• 脚本负责 git 分析、todo 解析、聚合、HTML->PDF
• resources 提供模板文件

---

下面我把笔记里最有价值的“造 Skill”内容，整理成我可以直接照抄的最小模板。

5.1 Step 1：创建技能文件夹

例如：weekly-report-generator/

5.2 Step 2：创建 SKILL.md（元数据）

— name: weekly-report-generator

description: 自动生成项目周报，从 git 提交、issue、todo 文件和用户输入中提取信息，生成结构化周报

Weekly Report Generator

核心流程

1. 收集数据
2. 处理数据
3. 组织周报结构
4. 生成报告

输出规范

• 输出 HTML：weekly-report-YYYY-MM-DD.html
• 输出 PDF：weekly-report-YYYY-MM-DD.pdf

验证方式

• 生成文件是否存在
• 数据统计是否与 git log/issue 数量一致

注意事项

• 非 git 仓库则跳过 git log 分析
• 无 todo/issue 则提示用户补充

  5.3 Step 3：把“资源层”做实（可选但强烈推荐）

  • scripts/git-analyzer.py
  • scripts/todo-parser.py
  • references/report-structure.md
  • assets/report-template.html

  5.4 把 Skill 用到“写博文”场景（实战落地思路）

  在日常写作中，一个典型的痛点是：文章结构相对固定，但材料来源（笔记、链接或混合内容）往往多变。这类“结构固定、输入多变”的工作，恰好是 Skills 擅长的应用场景：

  • 写作结构固定化：复用经过验证的博文模板；
  • 资料整理规则固定化：实现链接提取、要点归类及引用规范的自动化；
  • 产出物标准化：每篇文章都能稳定生成流程图、时序图及对应的绘图脚本。

  基于此思路，可以将写作流程拆解为两个核心技能：

  • java-middleware-blog-skill
  • ai-blog-skill

  并在 SKILL.md 里强制要求输出：

  • 快速参考
  • 概念表格
  • 原理流程图（Mermaid）
  • 实战步骤
  • 避坑与面试问答
  • 待确认清单

  ---

  实操建议：先不写脚本，先把 SOP + 输出规范写死，让 AI 稳定按流程产出；然后再把“最耗时/最确定”的步骤脚本化。

6.1 典型问题清单

1. 技能命中率低
   • 原因：name/description 太泛、与用户话术不匹配
   • 解决：把描述写成“动词+对象+场景”，并提供 2-3 个触发示例
2. 能生成但不稳定/跑偏
   • 原因：只有目标没有流程；没有输出规范与验证
   • 解决：补齐 SOP、输出 schema、验收清单
3. 材料来源杂，引用混乱
   • 原因：没有“可信度标注”与“引用区”
   • 解决：固定一个 references 模块，区分官方/第三方/个人笔记

6.2 **实践

• 先把“流程与验收标准”写清楚，再考虑脚本化
• Skill 输出尽量结构化（标题层级、表格、固定段落），方便我二次审核
• 对于带外部链接的内容，统一放“参考链接”区，并在正文标注来源类型

---

7.1 高频问题

• Q1：Skills 和 Prompt 有什么区别？
  • A：Prompt 更像一次性指令；Skill 是可复用能力包，包含元数据（触发）+ SOP（思考/规划）+ 资源（执行/校验），支持按需加载。
• Q2：为什么 Skills 能省 token？
  • A：因为平时只保留元数据（很小），只有命中意图才加载完整指令与资源，符合“渐进式披露”。
• Q3：如何衡量一个 Skill 写得好不好？
  • A：看四点：可触发（命中率）、可执行（SOP）、可校验（验收/验证）、可复用（输入输出稳定）。

7.2 进阶追问

• Skill / Tool / Agent 的边界怎么划？
  • Skill：流程与规范（SOP）
  • Tool：确定性动作
  • Agent：规划+调度+执行主体

本文为MY_TEUCK原创实战学习笔记，持续更新Java后端与AI应用领域干货，问题欢迎评论区交流。