1. Skills 的构成

一个标准的 Skill 定义包含以下几个核心部分：

组成部分 说明 状态
SKILL.md 核心说明文档，包含元数据（Metadata）和执行步骤。 ✅ 必选
scripts/ 可执行的脚本文件（如 Python、Node.js 脚本）。 ⚪ 可选
references/ 参考文档、详细指南或长篇幅的上下文背景。 ⚪ 可选
assets/ 模板、图片等静态资源文件。 ⚪ 可选

1.1 标准文件夹组织结构

Agent Skills 通常以标准化的文件夹结构进行组织，示例如下：

.joycode/skills/my-skill-folder/
├── SKILL.md           # 核心：包含指令和元数据
├── scripts/           # 可选：辅助脚本
│   └── process.py
├── references/        # 可选：详细参考文档
│   └── guide.md
└── assets/            # 可选：资源文件
    └── template.pdf

2. SKILL.md 标准格式

SKILL.md 是技能的核心，由顶部的 YAML 元数据（给 AI 路由看）和下方的 Markdown 主体（给 AI 执行看）组成。

---
# === 必需字段 ===
name: skill-name        # 技能唯一标识，建议使用 kebab-case
description: >
  简洁但精确的描述，这是给 Skill Router (路由) 看的。说明：
  1. 这个技能做什么
  2. 什么时候应该使用它
  3. 它的核心价值是什么

# === 可选字段 ===
version: 1.0.0
author: Your Name
tags: [database, analysis, sql]
---

# 技能标题

## 概述
（对技能的详细介绍与背景说明）

## 工作流程
自我纠错机制，在 Skill 中要求 AI 验证自己的输出：
1. 分析代码...
2. Self-Correction: 再次检查是否遗漏安全漏洞
3. 生成报告...
（详细的步骤说明）

## 最佳实践
（经验总结、执行该任务的注意事项）

## 示例
（具体的使用案例与输入输出参考）

3. 渐进式披露 (Progressive Disclosure)

为了优化 Token 使用和 AI 的上下文窗口，Skills 采用了“渐进式披露”的设计模式：

第一层：元数据（Metadata）

  • 系统启动时仅加载技能名称（Name）和简要描述（Description）。
  • 用于快速识别任务与技能的匹配度。
  • 消耗：每个技能仅约 100 个 Token。

第二层：技能主体（Instructions）

  • 当任务匹配时，加载完整的 SKILL.md 文档。
  • 用于理解输入参数、使用约束和执行方式。
  • 消耗：通常在 1000 - 5000 个 Token 之间。

第三层：附加资源（Scripts & References）

  • 真正执行具体步骤、需要深度上下文时才加载。
  • 包含脚本、配置文件、长篇参考文档等。
  • 优势：按需访问，避免浪费上下文空间。

4. 在项目中创建和使用 Skill

4.1 AI编程工具使用Skills

不同的 AI 编程工具对 Skills 目录的位置有不同的默认约定：

工具名称 默认目录位置 (全局或项目级)
Claude Code ~/.claude/skills/ 或项目级 .claude/skills/
Cursor ~/.cursor/skills/ 或项目级 .cursor/skills/
OpenCode ~/.opencode/skills/ 或 .opencode/skills/
joycode ~/.joycode/skills/ 或项目级 .joycode/skills/

推荐使用 openskills 在不同AI工具和项目中进行skills同步：

# 1. 安装“连接器” openskills
npm install -g openskills
# 2. 进货“技能包”, 默认 project-local (./.agent/skills). Use --global for ~/.agent/skills.
openskills install anthropics/skills --global
# 3. 注入灵魂（关键！）进入对应目录后执行，会生成一个AGENTS.md文件，让你的AI看见技能
openskills sync

4.2 openclaw 使用skills

步骤1：通过ClawHub安装Word文档生成技能插件

OpenClaw的扩展功能均通过Skills实现，Word生成插件需从官方技能市场ClawHub一键安装。打开终端（PowerShell或CMD命令提示符），运行以下命令安装官方Word文档生成技能：

# 安装最新版Word文档生成技能
npx clawhub@latest install word-docx

技能安装完成后会自动热重载生效，无需手动重启 OpenClaw。

步骤2：启用技能并关联至智能体

安装完成后，需要将word-docx技能启用并绑定到你的OpenClaw智能体，才能正常调用。
① 打开智能体配置文件：notepad $env:USERPROFILE.openclaw\agents\assistant-agent.yaml
② 在文件中找到skills:配置项，添加word-docx技能：

skills:
  - word-docx   # 新增Word文档生成技能
  - filesystem
  - websearch
  # 保留你已启用的其他技能

③ 配置修改后，需要重启OpenClaw Gateway使设置生效。

步骤3：验证插件安装与启用状态

执行命令检查Word生成技能是否正常可用，确认状态为Ready/active即为成功。

# 查看所有已安装的技能列表
openclaw skills list
# 单独查看word-docx技能详情
openclaw skills info word-docx

在输出结果中，可看到word-docx技能信息、版本、状态及支持功能（创建文档、编辑内容、设置格式、导出文件等）。

5. 设计 Skills 的黄金法则

编写高质量的 Skill 需要遵循以下原则：

法则 说明 示例
单一职责 一个 Skill 只做一件事 ✅ query-data
✅ generate-chart
❌ data-tool（太大）
精准描述 WHAT + WHEN 「当用户要求编写UI组件时使用」
惜字如金 不写 AI 已知的废话 ✅ Use pdfplumber
❌ PDF是常见文件格式...
渐进加载 复杂内容拆分到 references 边缘情况放到参考文档
命名规范 避免模糊、无意义的命名 好的命名：
name: jd-me-sender
name: frontend-design
name: pdf-text-extractor

6. 相关资源推荐

标签: Agent

添加新评论