メインコンテンツまでスキップ

技能系统

技能（Skill）是可复用的指令集，以 SKILL.md 文件形式存在。Agent 可以在运行时通过工具读取技能内容，将其作为额外的上下文注入对话。技能让你可以将领域知识、工作流程和最佳实践封装为标准化的可复用单元。

什么是技能​

技能本质上是一个包含 YAML frontmatter 和 Markdown 正文的文件：

---
name: 代码审查规范
description: 项目统一的代码审查标准和检查清单
---

# 代码审查规范

## 必检项

1. 是否遵循命名规范
2. 是否有未使用的 import
3. 文件行数是否超过上限
4. 是否有 console.log 遗留

## 评审模板

**文件**: `{文件名}`
**问题数**: {N}
**严重程度**: 高/中/低

| # | 问题 | 位置 | 建议 |
|---|------|------|------|
| 1 | ... | L42 | ... |

Agent 使用 list_skills 工具查看可用技能，然后用 read_skill 工具读取具体技能的内容，将其作为执行任务的参考。

技能发现位置​

技能按以下顺序被发现和加载：

优先级位置路径来源标识说明
1工作区.claude/skills/<name>/SKILL.mdworkspace当前项目专属
2项目<projectRoot>/.claude/skills/<name>/SKILL.mdproject项目级共享
3个人~/.claude/skills/<name>/SKILL.mdpersonal用户全局可用
4插件~/.elftia/plugins/skills/<name>/SKILL.mdplugin社区安装的技能
5内置应用内置builtinElftia 预装技能

同名技能中，优先级高的覆盖优先级低的。

技能工具​

Agent 通过两个内置工具与技能系统交互：

list_skills​

列出所有可用的技能及其描述。

参数： 无

返回示例：

Available skills:
- code-standards (workspace): 项目编码规范和最佳实践
- architecture-index (workspace): 项目架构索引和文件定位
- build-optimization (personal): 构建优化规范

read_skill​

读取指定技能的完整内容。

参数：

参数类型必填说明
namestring是技能名称

返回： 技能文件的完整 Markdown 内容。

SkillHub 社区市场​

SkillHub 是技能的社区市场，你可以搜索和安装其他用户分享的技能。

搜索技能​

Agent 可以使用 skillhub_search 工具搜索社区技能：

搜索 "React 最佳实践" 相关的技能

安装技能​

找到想要的技能后，使用 skillhub_install 工具安装到本地：

安装技能 "react-best-practices" 到个人目录

安装后的技能会保存到 ~/.elftia/plugins/skills/ 目录，所有项目都可以使用。

将技能关联到 Agent​

有两种方式将技能关联到 Agent：

方式 1：在 Agent 配置中声明​

在 Agent 的 frontmatter 中使用 skills 字段：

---
name: 代码助手
skills:
  - code-standards
  - architecture-index
---

这样配置后，Agent 启动时会自动将这些技能的内容注入系统提示。

方式 2：运行时手动读取​

Agent 在执行过程中可以主动调用 list_skills 和 read_skill 工具来获取技能内容：

用户：请按照项目规范审查这段代码
Agent：让我先查看可用的技能... [调用 list_skills]
Agent：找到了 code-standards 技能，让我读取它... [调用 read_skill]
Agent：根据规范，我发现以下问题...

创建自定义技能​

步骤​

  1. 选择技能的存储位置：

    • 项目专属 → .claude/skills/<name>/SKILL.md
    • 全局通用 → ~/.claude/skills/<name>/SKILL.md

  2. 创建目录和文件：

mkdir -p .claude/skills/my-skill
  1. 编写 SKILL.md 文件：
---
name: 我的技能
description: 一句话描述技能的用途
---

# 技能标题

技能的详细内容...

SKILL.md 格式参考​

基础格式​

---
name: 技能名称
description: 技能的简要描述
---

技能的正文内容（Markdown 格式）

完整格式（含扩展元数据）​

---
name: 技能名称
description: 技能描述
always: false
allowedTools:
  - Read
  - Grep
  - Glob
metadata:
  always: false
  emoji: "📋"
  os:
    - win32
    - darwin
    - linux
  requires:
    bins:
      - node
      - npm
    env:
      - GITHUB_TOKEN
---

技能正文...

Frontmatter 字段说明​

字段类型说明
namestring技能显示名称
descriptionstring简要描述
alwaysboolean是否始终加载到系统提示（默认 false）
allowedToolsstring[]使用此技能时允许的工具白名单
metadata.alwaysboolean同 always（嵌套格式）
metadata.emojistring显示图标
metadata.osstring[]平台限制（空 = 全平台）
metadata.requires.binsstring[]所需的 CLI 工具
metadata.requires.envstring[]所需的环境变量

always 技能​

设置 always: true 的技能会在每次 Agent 启动时自动加载到系统提示中，无需在 Agent 配置中声明。适合项目级的基础规范。

工具白名单​

allowedTools 字段可以限制使用该技能时 Agent 可用的工具集合。这在安全敏感的场景中很有用，例如：

allowedTools:
  - Read
  - Grep
  - Glob

这会将 Agent 的可用工具限制为只读工具。

技能编写最佳实践​

结构清晰​

---
name: API 设计规范
description: RESTful API 设计指南和命名规范
---

# API 设计规范

## 命名规则
- URL 使用 kebab-case
- 查询参数使用 camelCase

## 状态码使用
- 200: 成功
- 201: 已创建
- 400: 请求参数错误

## 检查清单
- [ ] URL 是否符合 RESTful 规范
- [ ] 是否有合适的错误处理
- [ ] 是否有分页支持

实用建议​

  1. 聚焦单一主题 — 一个技能解决一类问题
  2. 提供具体示例 — 包含代码片段和模板
  3. 使用检查清单 — 方便 Agent 系统化执行
  4. 标注适用范围 — 说明技能的前提条件和限制
  5. 保持简洁 — 避免技能内容过长，影响上下文窗口

常见问题​

问题原因解决方案
Agent 找不到技能技能文件不在正确路径或名称不匹配使用 list_skills 确认可用技能
技能内容未注入系统提示未在 Agent 配置中声明且 always 为 false在 skills 字段中添加或设置 always: true
技能依赖的工具不可用Agent 工具白名单不包含所需工具在 Agent 配置中添加必要的工具
平台限制导致技能不可用metadata.os 限制了当前平台修改 os 字段或在当前平台安装依赖
技能内容太长影响性能技能内容占用过多上下文窗口拆分为多个小技能，按需加载
SkillHub 搜索无结果搜索关键词不匹配尝试使用不同的关键词或英文搜索

相关链接​