技能系统

技能（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.md`	`workspace`	当前项目专属
2	项目	`<projectRoot>/.claude/skills/<name>/SKILL.md`	`project`	项目级共享
3	个人	`~/.claude/skills/<name>/SKILL.md`	`personal`	用户全局可用
4	插件	`~/.elftia/plugins/skills/<name>/SKILL.md`	`plugin`	社区安装的技能
5	内置	应用内置	`builtin`	Elftia 预装技能

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

技能工具

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

list_skills

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

参数： 无

返回示例：

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

read_skill

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

参数：

参数	类型	必填	说明
`name`	string	是	技能名称

返回： 技能文件的完整 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：根据规范，我发现以下问题...

创建自定义技能

步骤

选择技能的存储位置：
- 项目专属 → .claude/skills/<name>/SKILL.md
- 全局通用 → ~/.claude/skills/<name>/SKILL.md
创建目录和文件：

mkdir -p .claude/skills/my-skill

编写 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 字段说明

字段	类型	说明
`name`	string	技能显示名称
`description`	string	简要描述
`always`	boolean	是否始终加载到系统提示（默认 false）
`allowedTools`	string[]	使用此技能时允许的工具白名单
`metadata.always`	boolean	同 `always`（嵌套格式）
`metadata.emoji`	string	显示图标
`metadata.os`	string[]	平台限制（空 = 全平台）
`metadata.requires.bins`	string[]	所需的 CLI 工具
`metadata.requires.env`	string[]	所需的环境变量

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 规范
- [ ] 是否有合适的错误处理
- [ ] 是否有分页支持

实用建议

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

常见问题

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

什么是技能​

技能发现位置​

技能工具​

list_skills​

read_skill​

SkillHub 社区市场​

搜索技能​

安装技能​

将技能关联到 Agent​

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

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

创建自定义技能​

步骤​

SKILL.md 格式参考​

基础格式​

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

Frontmatter 字段说明​

always 技能​

工具白名单​

技能编写最佳实践​

结构清晰​

实用建议​

常见问题​

相关链接​