Skills

Skills 是扩展 Claude 功能的模块化能力，提供特定领域的专业知识。

了解更多

Skills 基于 Claude 的 Agent Skills 系统。详情请参阅 Claude Skills 官方文档。

什么是 Skills？

Skills 是基于文件系统的资源，为 Claude 提供：

• 特定领域的专业知识和工作流
• 项目特定的上下文和最佳实践
• 跨对话的可复用能力

与一次性提示词不同，Skills 按需加载，无需重复提供相同的指导。

Skills 工作原理

Skills 使用渐进式披露 - 按需分阶段加载内容：

层级	加载时机	内容
元数据	始终（启动时）	YAML frontmatter 中的 name 和 description
指令	触发 Skill 时	SKILL.md 正文中的指导内容
资源	按需	附加文件、脚本、参考资料

这确保任何时候只有相关内容占用上下文窗口。

Skill 结构

每个 Skill 是一个包含 SKILL.md 文件的目录：

my-skill/
├── SKILL.md          # 主要指令（必需）
├── REFERENCE.md      # 附加指导（可选）
└── scripts/          # 工具脚本（可选）
    └── helper.py

SKILL.md 格式

---
name: code-reviewer
description: 专业代码审查助手。用于审查代码、检查 bug 或评估代码质量时使用。
---

# 代码审查 Skill

## 指令

审查代码时：
1. 检查 bug 和错误
2. 评估性能影响
3. 提出改进建议
4. 遵循语言特定的最佳实践

## 响应格式

- 以摘要开始
- 按严重程度列出问题
- 提供具体建议

必填字段

• name：唯一标识符（仅限小写字母、数字、连字符，最多 64 字符）
• description：Skill 的功能和使用时机（最多 1024 字符）

WARNING

description 非常关键 - Claude 用它来决定何时激活 Skill。需要同时包含功能描述和使用场景。

Skill 位置

Alma 从多个位置加载 Skills，按以下优先级排序（高优先级覆盖低优先级）：

个人 Skills

~/.config/alma/skills/

你的个人 Skills，在所有对话中可用。具有最高优先级。

Claude Code Skills

~/.claude/skills/

来自 Claude Code 的 Skills，在 Alma 和 Claude Code CLI 之间共享。

市场 Skills

从 Claude 插件市场安装的 Skills。

项目 Skills

<workspace>/.alma/skills/

项目特定的 Skills，当工作区激活时自动加载。适用于：

• 团队共享的编码规范和约定
• 项目特定的工作流和脚本
• 仓库特定的文档助手

项目 Skills 自动加载

当你打开一个带有工作区的对话时，Alma 会自动检测并加载该工作区 .alma/skills/ 目录中的 Skills。这些 Skills 会出现在技能选择器中，可以立即使用。

优先级顺序

当 Skills 同名时，以下优先级决定使用哪个：

1. 个人（最高）- ~/.config/alma/skills/
2. Claude Code - ~/.claude/skills/
3. 市场 - 已安装的插件
4. 项目（最低）- <workspace>/.alma/skills/

使用 Skills

自动激活

当你的请求匹配 Skill 的 description 时，Claude 会自动使用该 Skill。无需显式调用。

显式引用

你也可以在消息中提及 Skill 名称以确保使用它。

Skill 内容类型

Skills 可以包含三种类型的内容：

指令（Markdown）

markdown 文件中的工作流、最佳实践和指导。

代码（脚本）

Claude 可以运行的可执行脚本。脚本代码不会进入上下文窗口 - 只有输出会。

资源

参考材料，如文档、数据库模式、模板或示例。

Skill 管理

查看 Skills

1. 前往 设置 → Skills
2. 浏览可用的 Skills
3. 按位置筛选

启用/禁用

切换 Skills 的开/关状态而不删除它们。

刷新

修改后点击 刷新 从磁盘重新加载 Skills。

示例

写作助手

writing-assistant/
└── SKILL.md

---
name: writing-assistant
description: 专业写作助手。用于起草文档、编辑文本或提升写作质量时使用。
---

# 写作助手

帮助完成：
- 博客文章
- 技术文档
- 营销文案
- 邮件草稿

遵循这些原则：
- 清晰简洁
- 主动语态
- 适当的语气
- 正确的语法

项目上下文

project-context/
├── SKILL.md
└── ARCHITECTURE.md

---
name: project-context
description: MyApp 项目的特定知识。在处理此代码库时使用。
---

# 项目：MyApp

## 快速参考
- React 前端 + TypeScript
- Node.js 后端
- PostgreSQL 数据库

详细架构请参阅 [ARCHITECTURE.md](ARCHITECTURE.md)。

## 常用任务
- 启动开发：`npm run dev`
- 测试：`npm test`
- 构建：`npm run build`

最佳实践

编写清晰的描述

description 决定 Claude 何时使用你的 Skill。需要包含：

• Skill 的功能
• 何时应该使用
• 关键触发词

保持专注

每个 Skill 应该有一个清晰、单一的目的。

使用渐进式披露

将核心信息放在 SKILL.md 中，详细参考放在单独的文件中。

版本控制

将 Skills 存储在 git 中以便版本管理和分享。

故障排除

"Skill 无法加载"

• 检查 Skill 目录中是否存在 SKILL.md
• 验证 YAML frontmatter 语法（必须有 name 和 description）
• 点击刷新重新加载

"Skill 未激活"

• 检查 description 是否与你的请求上下文匹配
• 确保 Skill 已启用
• 尝试显式提及 Skill 名称