Skill 是一组存储在 SKILL.md 文件中的本地指令，包含：

• 名称和描述：用于识别和匹配 Skill
• 使用规则：何时以及如何应用该 Skill
• 最佳实践：领域特定的知识和模式
• 参考资源：相关的代码示例、模板和文档

Skill 文件结构

---
name: skill-name
description: 描述这个 Skill 的用途
metadata:
    tags: tag1, tag2, tag3
---

# Skill 名称

描述在什么场景下应该使用这个 Skill。

• 链接到规则文件或参考文档
• 提供代码示例
• 说明最佳实践

Memo 在启动时自动扫描以下位置来发现 Skills：

项目级 Skills

• .<agent>/skills 目录（例如：.agents/skills、.claude/skills、.codex/skills）
• 扫描深度：最多 6 层子目录

用户级 Skills

• $MEMO_HOME/skills（默认为 ~/.memo/skills）
• ~/.claude/skills
• ~/.codex/skills
• ~/.agents/skills

去重

Skills 会按其 SKILL.md 内容的 sha256 哈希去重。当同一个 skill 存在于多个位置时 （例如同时安装在 ~/.claude/skills 和 ~/.agents/skills），只保留优先级最高的副本， 顺序如下：

1. 项目级根目录
2. $MEMO_HOME/skills
3. ~/.claude/skills
4. ~/.codex/skills
5. ~/.agents/skills

其余副本仍可作为别名解析——见 配置默认激活 Skills。

内置 Skills

Memo 内置 skill-creator skill。每次会话启动时，如果 $MEMO_HOME/skills（默认为 ~/.memo/skills）中还没有它，Memo 会幂等地安装，开箱即用。

安装是非破坏性的：

• 未被修改过的旧版内置副本会在 Memo 升级内容时被自动更新
• 被你自己修改过（或由其他工具安装）的副本永远不会被覆盖。如需重新安装内置版本， 删除该目录即可

如果你同时使用 Claude Code，它的 ~/.claude/skills/skill-creator 是另一个 skill （内容不同，不去重），两者会同时出现在 skills 列表中。可用 memo skills read /absolute/path/to/SKILL.md 指定路径区分。

排除的目录

• .git/ 和 node_modules/

1. 选择位置

项目特定 Skill：放在项目根目录的 .codex/skills/<skill-name>/SKILL.md

全局 Skill：放在 ~/.memo/skills/<skill-name>/SKILL.md

2. 编写 SKILL.md

---
name: react-hooks
description: Best practices for React Hooks usage and custom hooks creation
---

# React Hooks Best Practices

Use this skill when working with React Hooks, including:

• Built-in hooks (useState, useEffect, useContext, etc.)
• Custom hooks creation
• Hooks performance optimization

1. useEffect dependencies: Always specify the complete dependency array
2. Custom hooks naming: Start with use prefix
3. Cleanup side effects: Return cleanup functions in useEffect when needed

• ./rules/useEffect.md
• ./examples/custom-hook.ts

### 3. 添加规则文件（可选）

```md
<!-- .codex/skills/react-hooks/rules/useEffect.md -->

# useEffect Best Practices

• Include all values from the component scope used inside useEffect
• Use functional updates when current state is needed
• Consider using useCallback for function dependencies

• Missing dependencies causing stale closures
• Infinite loops from object/array dependencies
• Race conditions in async effects

显式调用

在提示中通过 $skill-name 语法显式调用：

请帮我优化这个组件的 hooks 使用 $react-hooks

使用最佳实践重构这段代码 $doc-writing

自动匹配

当任务描述与某个 Skill 的描述高度匹配时，Memo 会自动建议使用该 Skill。

查看可用 Skills

在会话中，Memo 会将所有发现的 Skills 列在系统提示中：

A skill is a set of local instructions to follow that is stored in a SKILL.md file...

Available skills

• react-hooks: Best practices for React Hooks usage...
• doc-writing: Generate and update technical documentation...

技能目录受上下文预算限制；超出时描述会被截断，多余的 skills 会被省略（并附说明）。
需要时可使用 `read_skill` 工具按需加载某个 skill 的完整 `SKILL.md`。

### 使用 read_skill 工具读取 Skill

当你决定使用某个 skill 时，`read_skill` 工具会加载它的完整指令：

- 传入技能目录中的 skill `name`，或名称有歧义时传入精确的 `SKILL.md` `path`
- 会自动去除 frontmatter
- 返回结果包含 `skill_directory`，skill 中的相对路径（如 `scripts/foo.py`、`references/`）都基于它解析
- 特别长的 skill 可能会被工具输出限制截断

在 config.toml 中设置默认激活的 Skills：

# 激活所有发现的 Skills（默认）
# active_skills 未设置时

# 不激活任何 Skill
active_skills = []

# 指定激活特定的 Skills
active_skills = [
  "/absolute/path/to/.codex/skills/react-hooks/SKILL.md",
  "/absolute/path/to/.memo/skills/doc-writing/SKILL.md"
]

注意：active_skills 存储的是 SKILL.md 文件的绝对路径。 指向去重副本（例如当 ~/.claude/skills 去重胜出时指向 ~/.agents/skills/react-hooks/SKILL.md）的路径仍会激活该 skill。

列出所有发现的 Skills（跨项目级和用户级根目录，已去重）：

memo skills list
memo skills list --json

读取某个 Skill 的完整指令：

memo skills read react-hooks
memo skills read /absolute/path/to/.codex/skills/react-hooks/SKILL.md
memo skills read react-hooks --json

当名称匹配多个 skills 时，read 会列出候选路径；传入精确路径即可区分。

Memo 内置以下 Skills 使用规则：

1. 触发规则：

   • 用户明确命名 Skill（使用 $SkillName 或纯文本）
   • 任务描述与某个 Skill 的描述明显匹配
   • 多个提及意味着全部使用

2. 使用方法（渐进式披露）：

   • 首先读取 SKILL.md 了解工作流程
   • 当 SKILL.md 引用相对路径时，优先相对于 Skill 目录解析
   • 如果存在 scripts/ 目录，优先运行或修补脚本
   • 如果存在 assets/ 或模板，优先复用而非从头创建

3. 上下文管理：

   • 保持上下文精简：总结长段落而不是粘贴全部
   • 仅在需要时加载额外文件
   • 避免深度引用追踪

4. 安全与回退：

   • 如果 Skill 无法干净地应用，说明问题并选择次优方案继续

组织复杂的 Skills

.skills/
└── my-skill/
    ├── SKILL.md              # 主入口
    ├── rules/                # 规则文档
    │   ├── rule1.md
    │   └── rule2.md
    ├── examples/             # 代码示例
    │   ├── example1.ts
    │   └── example2.ts
    ├── scripts/              # 可执行脚本
    │   └── helper.js
    └── assets/               # 模板和资源
        └── template.tsx

Skill 命名建议

• 使用小写字母和连字符（kebab-case）
• 名称应清晰描述领域或用途
• 避免与内置工具名称冲突
• 长度限制：64 个字符

描述编写建议

• 简洁说明 Skill 的用途
• 包含关键词以便自动匹配
• 长度限制：1024 个字符

Skill 未被识别

1. 确认 SKILL.md 存在且文件名为大写
2. 检查 frontmatter 是否包含 name 和 description
3. 验证 Skill 目录在扫描路径内
4. 重启 Memo 或创建新会话

Skill 内容过长

• 将详细内容拆分到 rules/ 子目录
• 在 SKILL.md 中只保留概述和链接
• 使用渐进式披露，按需加载具体内容

Skill 未生效

1. 检查 config.toml 中的 active_skills 配置
2. 在 Web UI 中确认 Skill 处于激活状态
3. 确保在提示中正确使用了 $skill-name 语法

• MCP 集成：外部工具集成
• 配置：config.toml 详解