---
name: skill
description: 管理本地技能 - 列出、添加、删除、搜索、编辑、设置向导
argument-hint: "<command> [args]"
level: 2
---

# Skill 管理 CLI

这是一个用于通过类 CLI 命令管理 oh-my-claudecode 技能的元技能。

## 子命令

### /skill list

按作用域组织显示所有可用技能。

**行为：**
1. 扫描插件 `skills/` 目录中打包的内置技能（只读）
2. 扫描位于 `~/.claude/skills/omc-learned/` 的用户技能
3. 扫描位于 `.omc/skills/` 的项目技能
4. 解析 YAML frontmatter 以提取元数据
5. 以有组织的表格格式显示：

```
内置技能（随 oh-my-claudecode 打包提供）：
| Name              | Description                    | Scope    |
|-------------------|--------------------------------|----------|
| visual-verdict    | Structured visual QA verdicts  | built-in |
| ralph             | Persistence loop               | built-in |

用户技能（~/.claude/skills/omc-learned/）：
| Name              | Triggers           | Quality | Usage | Scope |
|-------------------|--------------------|---------|-------|-------|
| error-handler     | fix, error         | 95%     | 42    | user  |
| api-builder       | api, endpoint      | 88%     | 23    | user  |

项目技能（.omc/skills/）：
| Name              | Triggers           | Quality | Usage | Scope   |
|-------------------|--------------------|---------|-------|---------|
| test-runner       | test, run          | 92%     | 15    | project |
```

**兜底：** 如果没有质量/使用统计信息，则显示 `"N/A"`

**内置技能说明：** 内置技能随 oh-my-claudecode 一起提供，可被发现和读取，但不能通过 `/skill remove` 或 `/skill edit` 删除或编辑。

---

### /skill add [name]

用于创建新技能的交互式向导。

**行为：**
1. **询问技能名称**（如果命令中未提供）
   - 校验：仅允许小写字母和连字符，不允许空格
2. **询问描述**
   - 清晰简洁的一行说明
3. **询问触发词**（以逗号分隔的关键字）
   - 示例：`"error, fix, debug"`
4. **询问参数提示**（可选）
   - 示例：`"<file> [options]"`
5. **询问作用域：**
   - `user` → `~/.claude/skills/omc-learned/<name>/SKILL.md`
   - `project` → `.omc/skills/<name>/SKILL.md`
6. **使用模板创建技能文件：**

```yaml
---
name: <name>
description: <description>
triggers:
  - <trigger1>
  - <trigger2>
argument-hint: "<args>"
---

# <Name> Skill

## Purpose

[描述这个技能的作用]

## When to Activate

[描述触发条件和适用场景]

## Workflow

1. [步骤 1]
2. [步骤 2]
3. [步骤 3]

## Examples

```
/oh-my-claudecode:<name> example-arg
```

## Notes

[附加上下文、边界情况、注意事项]
```

7. **报告成功**并附上文件路径
8. **建议：** `“Edit /skill edit <name> to customize content”`

**示例：**
```
User: /skill add custom-logger
Assistant: 正在创建新技能 'custom-logger'...

Description: Enhanced logging with structured output
Triggers (comma-separated): log, logger, logging
Argument hint (optional): <level> [message]
Scope (user/project): user

✓ 已在 ~/.claude/skills/omc-learned/custom-logger/SKILL.md 创建技能
→ 编辑命令：/skill edit custom-logger
```

---

### /skill remove <name>

按名称删除技能。

**行为：**
1. **在两个作用域中搜索技能：**
   - `~/.claude/skills/omc-learned/<name>/SKILL.md`
   - `.omc/skills/<name>/SKILL.md`
2. **如果找到：**
   - 显示技能信息（名称、描述、作用域）
   - **请求确认：** `“Delete '<name>' skill from <scope>? (yes/no)”`
3. **如果已确认：**
   - 删除整个技能目录（例如 `~/.claude/skills/omc-learned/<name>/`）
   - 报告：`“✓ Removed skill '<name>' from <scope>”`
4. **如果未找到：**
   - 报告：`“✗ Skill '<name>' not found in user or project scope”`

**安全性：** 未经用户明确确认，绝不删除。

**示例：**
```
User: /skill remove old-logger
Assistant: 在 user 作用域中找到技能 'old-logger'：
  Description: Legacy logging utility
  Scope: user (~/.claude/skills/omc-learned/)

删除技能 'old-logger'？(yes/no)

User: yes
Assistant: ✓ 已从 user 作用域移除技能 'old-logger'
```

---

### /skill edit <name>

以交互方式编辑现有技能。

**行为：**
1. **按名称查找技能**（搜索两个作用域）
2. 通过 Read 工具**读取当前内容**
3. **显示当前值：**
   ```
   当前技能 'custom-logger'：
   - Description: Enhanced logging with structured output
   - Triggers: log, logger, logging
   - Argument hint: <level> [message]
   - Scope: user
   ```
4. **询问要修改什么：**
   - `description` - 更新描述
   - `triggers` - 更新触发关键字
   - `argument-hint` - 更新参数提示
   - `content` - 编辑完整 Markdown 内容
   - `rename` - 重命名技能（移动文件）
   - `cancel` - 不做修改并退出
5. **对于所选字段：**
   - 显示当前值
   - 询问新值
   - 更新 YAML frontmatter 或正文内容
   - 写回文件
6. **报告成功**并总结改动内容

**示例：**
```
User: /skill edit custom-logger
Assistant: 当前技能 'custom-logger'：
  - Description: Enhanced logging with structured output
  - Triggers: log, logger, logging
  - Argument hint: <level> [message]

你想编辑什么？(description/triggers/argument-hint/content/rename/cancel)

User: triggers
Assistant: 当前触发词：log, logger, logging
New triggers (comma-separated): log, logger, logging, trace

✓ 已更新 'custom-logger' 的 triggers
```

---

### /skill search <query>

按内容、触发词、名称或描述搜索技能。

**行为：**
1. **扫描两个作用域中的所有技能**
2. **匹配查询**（不区分大小写），匹配范围包括：
   - 技能名称
   - 描述
   - 触发词
   - 完整 Markdown 内容
3. **显示匹配结果**及上下文：

```
找到 3 个匹配 "typescript error" 的技能：

1. typescript-fixer (user)
   Description: Fix common TypeScript errors
   Match: "typescript error handling patterns"

2. error-handler (user)
   Description: Generic error handling utilities
   Match: "Supports TypeScript and JavaScript errors"

3. lint-fix (project)
   Description: Auto-fix linting errors
   Match: "TypeScript ESLint error resolution"
```

**排序：** 名称/触发词命中的优先级高于正文内容命中

**示例：**
```
User: /skill search api endpoint
Assistant: 找到 2 个匹配 "api endpoint" 的技能：

1. api-builder (user)
   Description: Generate REST API endpoints
   Triggers: api, endpoint, rest

2. backend-scaffold (project)
   Description: Scaffold backend services
   Match: "Creates API endpoint boilerplate"
```

---

### /skill info <name>

显示技能的详细信息。

**行为：**
1. **按名称查找技能**（搜索两个作用域）
2. **解析 YAML frontmatter** 和正文内容
3. **显示完整详情：**

```
Skill: custom-logger
Scope: user (~/.claude/skills/omc-learned/custom-logger/)
Description: Enhanced logging with structured output
Triggers: log, logger, logging
Argument Hint: <level> [message]
Quality: 95% (if available)
Usage Count: 42 times (if available)
File Path: /home/user/.claude/skills/omc-learned/custom-logger/SKILL.md

--- FULL CONTENT ---
[完整的 markdown 内容]
```

**如果未找到：** 报错并建议使用 `/skill search`

**示例：**
```
User: /skill info custom-logger
Assistant: Skill: custom-logger
Scope: user
Description: Enhanced logging with structured output
Triggers: log, logger, logging
File: ~/.claude/skills/omc-learned/custom-logger/SKILL.md

--- CONTENT ---
# Custom Logger Skill

## Purpose
Enhanced logging with structured JSON output...
[其余内容]
```

---

### /skill sync

在用户和项目作用域之间同步技能。

**行为：**
1. **扫描两个作用域：**
   - 用户技能：`~/.claude/skills/omc-learned/`
   - 项目技能：`.omc/skills/`
2. **对比并分类：**
   - 仅用户侧存在的技能（项目中没有）
   - 仅项目侧存在的技能（用户中没有）
   - 两边都存在的公共技能
3. **显示同步机会：**

```
同步报告：

仅用户侧技能（5）：
  - error-handler
  - api-builder
  - custom-logger
  - test-generator
  - deploy-helper

仅项目侧技能（2）：
  - test-runner
  - backend-scaffold

公共技能（3）：
  - frontend-ui-ux
  - git-master
  - planner

选项：
  [1] 将用户技能复制到项目
  [2] 将项目技能复制到用户
  [3] 查看差异
  [4] 取消
```

4. **处理用户选择：**
   - 选项 1：选择要复制到项目的技能
   - 选项 2：选择要复制到用户的技能
   - 选项 3：为公共技能显示并排 diff
   - 选项 4：退出

**安全性：** 未经确认绝不覆盖

**示例：**
```
User: /skill sync
Assistant: 发现 5 个仅用户侧技能和 2 个仅项目侧技能。

将 'error-handler' 从 user 复制到 project？(yes/no/skip)
User: yes
Assistant: ✓ 已将 'error-handler' 复制到 .omc/skills/

将 'api-builder' 从 user 复制到 project？(yes/no/skip)
User: skip
...
```

---

### /skill setup

用于设置和管理本地技能的交互式向导（原名 `local-skills-setup`）。

**行为：**

#### 第 1 步：目录检查与设置

首先，检查技能目录是否存在，并在需要时创建：

```bash
# 检查并创建用户级技能目录
USER_SKILLS_DIR="$HOME/.claude/skills/omc-learned"
if [ -d "$USER_SKILLS_DIR" ]; then
  echo "User skills directory exists: $USER_SKILLS_DIR"
else
  mkdir -p "$USER_SKILLS_DIR"
  echo "Created user skills directory: $USER_SKILLS_DIR"
fi

# 检查并创建项目级技能目录
PROJECT_SKILLS_DIR=".omc/skills"
if [ -d "$PROJECT_SKILLS_DIR" ]; then
  echo "Project skills directory exists: $PROJECT_SKILLS_DIR"
else
  mkdir -p "$PROJECT_SKILLS_DIR"
  echo "Created project skills directory: $PROJECT_SKILLS_DIR"
fi
```

#### 第 2 步：技能扫描与清单

扫描两个目录并展示完整清单：

```bash
# 扫描用户级技能
echo "=== USER-LEVEL SKILLS (~/.claude/skills/omc-learned/) ==="
if [ -d "$HOME/.claude/skills/omc-learned" ]; then
  USER_COUNT=$(find "$HOME/.claude/skills/omc-learned" -name "*.md" 2>/dev/null | wc -l)
  echo "Total skills: $USER_COUNT"

  if [ $USER_COUNT -gt 0 ]; then
    echo ""
    echo "Skills found:"
    find "$HOME/.claude/skills/omc-learned" -name "*.md" -type f -exec sh -c '
      FILE="$1"
      NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
      DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
      MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null || stat -f "%Sm" "$FILE" 2>/dev/null)
      echo "  - $NAME"
      [ -n "$DESC" ] && echo "    Description: $DESC"
      echo "    Modified: $MODIFIED"
      echo ""
    ' sh {} \;
  fi
else
  echo "Directory not found"
fi

echo ""
echo "=== PROJECT-LEVEL SKILLS (.omc/skills/) ==="
if [ -d ".omc/skills" ]; then
  PROJECT_COUNT=$(find ".omc/skills" -name "*.md" 2>/dev/null | wc -l)
  echo "Total skills: $PROJECT_COUNT"

  if [ $PROJECT_COUNT -gt 0 ]; then
    echo ""
    echo "Skills found:"
    find ".omc/skills" -name "*.md" -type f -exec sh -c '
      FILE="$1"
      NAME=$(grep -m1 "^name:" "$FILE" 2>/dev/null | sed "s/name: //")
      DESC=$(grep -m1 "^description:" "$FILE" 2>/dev/null | sed "s/description: //")
      MODIFIED=$(stat -c "%y" "$FILE" 2>/dev/null || stat -f "%Sm" "$FILE" 2>/dev/null)
      echo "  - $NAME"
      [ -n "$DESC" ] && echo "    Description: $DESC"
      echo "    Modified: $MODIFIED"
      echo ""
    ' sh {} \;
  fi
else
  echo "Directory not found"
fi

# 汇总
TOTAL=$((USER_COUNT + PROJECT_COUNT))
echo "=== SUMMARY ==="
echo "Total skills across all directories: $TOTAL"
```

#### 第 3 步：快速操作菜单

扫描完成后，使用 AskUserQuestion 工具提供这些选项：

**问题：** `“What would you like to do with your local skills?”`

**选项：**
1. **Add new skill** - 启动技能创建向导（调用 `/skill add`）
2. **List all skills with details** - 显示完整技能清单（调用 `/skill list`）
3. **Scan conversation for patterns** - 分析当前对话中的可提炼技能模式
4. **Import skill** - 从 URL 导入技能或粘贴内容
5. **Done** - 退出向导

**选项 3：扫描对话中的模式**

分析当前对话上下文，识别潜在的可提炼技能模式。重点查找：
- 最近的调试会话，其中包含不明显的解决方案
- 需要调查才能解决的棘手 bug
- 发现的代码库特定变通方案
- 耗费时间才解决的错误模式

报告发现结果，并询问用户是否要将其中某些内容提炼为技能（如果是，则调用 `/learner`）。

**选项 4：导入技能**

询问用户提供以下任一内容：
- **URL**：从 URL 下载技能（例如 GitHub gist）
- **Paste content**：直接粘贴技能 markdown 内容

然后询问作用域：
- **User-level** (`~/.claude/skills/omc-learned/`) - 可在所有项目中使用
- **Project-level** (`.omc/skills/`) - 仅用于当前项目

校验技能格式，并保存到所选位置。

---

### /skill scan

用于扫描两个技能目录的快捷命令（`/skill setup` 的子集）。

**行为：**
运行 `/skill setup` 第 2 步中的扫描流程，但不进入交互式向导。

---

## 技能模板

通过 `/skill add` 或 `/skill setup` 创建技能时，为常见技能类型提供快捷模板：

### 错误解决模板

```markdown
---
id: error-[unique-id]
name: [Error Name]
description: 用于解决[特定上下文中的特定错误]
source: conversation
triggers: ["error message fragment", "file path", "symptom"]
quality: high
---

# [Error Name]

## The Insight
这个错误的根本原因是什么？你发现了什么原理？

## Why This Matters
如果不知道这一点会出什么问题？是什么症状引导你来到这里？

## Recognition Pattern
你如何判断这种情况适用？有哪些迹象？
- Error message: "[exact error]"
- File: [specific file path]
- Context: [when does this occur]

## The Approach
分步解决方案：
1. [带文件/行引用的具体操作]
2. [带文件/行引用的具体操作]
3. [验证步骤]

## Example
\`\`\`typescript
// Before (broken)
[problematic code]

// After (fixed)
[corrected code]
\`\`\`
```

### 工作流技能模板

```markdown
---
id: workflow-[unique-id]
name: [Workflow Name]
description: 用于[此代码库中特定任务]的流程
source: conversation
triggers: ["task description", "file pattern", "goal keyword"]
quality: high
---

# [Workflow Name]

## The Insight
是什么让这个工作流不同于显而易见的做法？

## Why This Matters
如果不遵循这个流程，会在哪里失败？

## Recognition Pattern
你应该在什么时候使用这个工作流？
- Task type: [specific task]
- Files involved: [specific patterns]
- Indicators: [how to recognize]

## The Approach
1. [包含具体命令/文件的步骤]
2. [包含具体命令/文件的步骤]
3. [验证]

## Gotchas
- [常见错误以及如何避免]
- [边界情况以及如何处理]
```

### 代码模式模板

```markdown
---
id: pattern-[unique-id]
name: [Pattern Name]
description: 用于[此代码库中特定用例]的模式
source: conversation
triggers: ["code pattern", "file type", "problem domain"]
quality: high
---

# [Pattern Name]

## The Insight
这个模式背后的关键原则是什么？

## Why This Matters
这个模式在这个代码库中解决了什么问题？

## Recognition Pattern
你在什么时候应用这个模式？
- File types: [specific files]
- Problem: [specific problem]
- Context: [codebase-specific context]

## The Approach
这是决策启发式，而不仅仅是代码：
1. [基于原则的步骤]
2. [基于原则的步骤]

## Example
\`\`\`typescript
[展示该原则的说明性示例]
\`\`\`

## Anti-Pattern
不要这样做，以及原因：
\`\`\`typescript
[需要避免的常见错误]
\`\`\`
```

### 集成技能模板

```markdown
---
id: integration-[unique-id]
name: [Integration Name]
description: [system A] 与 [system B] 在此代码库中的集成方式
source: conversation
triggers: ["system name", "integration point", "config file"]
quality: high
---

# [Integration Name]

## The Insight
这些系统的连接方式有哪些不明显之处？

## Why This Matters
如果你不了解这项集成，会有什么东西出问题？

## Recognition Pattern
你在什么时候是在处理这项集成？
- Files: [specific integration files]
- Config: [specific config locations]
- Symptoms: [what indicates integration issues]

## The Approach
如何正确处理这项集成：
1. [带文件路径的配置步骤]
2. [带具体细节的设置步骤]
3. [验证步骤]

## Gotchas
- [集成特定陷阱 #1]
- [集成特定陷阱 #2]
```

---

## 错误处理

**所有命令都必须处理：**
- 文件/目录不存在
- 权限错误
- 无效的 YAML frontmatter
- 重复的技能名称
- 无效的技能名称（空格、特殊字符）

**错误格式：**
```
✗ Error: <clear message>
→ Suggestion: <helpful next step>
```

---

## 使用示例

```bash
# 列出所有技能
/skill list

# 创建新技能
/skill add my-custom-skill

# 删除技能
/skill remove old-skill

# 编辑现有技能
/skill edit error-handler

# 搜索技能
/skill search typescript error

# 获取详细信息
/skill info my-custom-skill

# 在作用域之间同步
/skill sync

# 运行设置向导
/skill setup

# 快速扫描
/skill scan
```

## 使用模式

### 直接命令模式

当带参数调用时，跳过交互式向导：

- `/oh-my-claudecode:skill list` - 显示详细技能清单
- `/oh-my-claudecode:skill add` - 开始创建技能（调用 learner）
- `/oh-my-claudecode:skill scan` - 扫描两个技能目录

### 交互模式

当不带参数调用时，运行完整的引导式向导。

---

## 本地技能的好处

**自动应用：** Claude 会检测触发条件并自动应用技能，无需记住或搜索解决方案。

**版本控制：** 项目级技能（`.omc/skills/`）会随代码一起提交，因此整个团队都能受益。

**不断演化的知识：** 随着你发现更好的方法并优化触发词，技能会不断改进。

**减少 Token 使用：** Claude 不必重复解决同样的问题，而是高效复用已知模式。

**代码库记忆：** 保留原本会丢失在对话历史中的机构知识。

---

## 技能质量指南

优秀的技能应当具备：

1. **难以通过搜索直接获得** - 不能轻易通过搜索引擎找到
   - BAD: `"How to read files in TypeScript"`
   - GOOD: `"This codebase uses custom path resolution requiring fileURLToPath"`

2. **上下文特定** - 引用这个代码库中的实际文件/错误
   - BAD: `"Use try/catch for error handling"`
   - GOOD: `"The aiohttp proxy in server.py:42 crashes on ClientDisconnectedError"`

3. **可精确执行** - 明确说明做什么以及在哪里做
   - BAD: `"Handle edge cases"`
   - GOOD: `"When seeing 'Cannot find module' in dist/, check tsconfig.json moduleResolution"`

4. **来之不易** - 需要大量调试努力才能获得
   - BAD: 通用编程模式
   - GOOD: `"Race condition in worker.ts - Promise.all at line 89 needs await"`

---

## 相关技能

- `/oh-my-claudecode:learner` - 从当前对话中提炼技能
- `/oh-my-claudecode:note` - 保存快速笔记（比技能更轻量、没那么正式）
- `/oh-my-claudecode:deepinit` - 生成 `AGENTS.md` 代码库层级结构

---

## 示例会话

```
> /oh-my-claudecode:skill list

正在检查技能目录...
✓ User skills directory exists: ~/.claude/skills/omc-learned/
✓ Project skills directory exists: .omc/skills/

正在扫描技能...

=== USER-LEVEL SKILLS ===
Total skills: 3
  - async-network-error-handling
    Description: Pattern for handling independent I/O failures in async network code
    Modified: 2026-01-20 14:32:15

  - esm-path-resolution
    Description: Custom path resolution in ESM requiring fileURLToPath
    Modified: 2026-01-19 09:15:42

=== PROJECT-LEVEL SKILLS ===
Total skills: 5
  - session-timeout-fix
    Description: Fix for sessionId undefined after restart in session.ts
    Modified: 2026-01-22 16:45:23

  - build-cache-invalidation
    Description: When to clear TypeScript build cache to fix phantom errors
    Modified: 2026-01-21 11:28:37

=== SUMMARY ===
Total skills: 8

你想执行什么操作？
1. Add new skill
2. List all skills with details
3. Scan conversation for patterns
4. Import skill
5. Done
```

---

## 给用户的建议

- 定期运行 `/oh-my-claudecode:skill list` 来检查你的技能库
- 解决棘手 bug 后，立刻运行 learner 将其记录下来
- 对代码库特定知识使用项目级技能
- 对适用于所有场景的通用模式使用用户级技能
- 持续审阅并优化触发词，以提升匹配准确性

---

## 实现说明

1. **YAML 解析：** 使用 frontmatter 提取元数据
2. **文件操作：** 使用 Read/Write 工具，新文件绝不使用 Edit
3. **用户确认：** 破坏性操作必须始终确认
4. **清晰反馈：** 使用对勾（`✓`）、叉号（`✗`）、箭头（`→`）提升清晰度
5. **作用域解析：** 始终同时检查 user 和 project 两个作用域
6. **校验：** 强制执行命名约定（仅小写字母和连字符）

---

## 相关技能

- `/oh-my-claudecode:learner` - 从当前对话中提炼技能
- `/oh-my-claudecode:note` - 保存快速笔记（比技能更轻量、没那么正式）
- `/oh-my-claudecode:deepinit` - 生成 `AGENTS.md` 代码库层级结构

---

## 后续增强

- `/skill export <name>` - 将技能导出为可共享文件
- `/skill import <file>` - 从文件导入技能
- `/skill stats` - 显示所有技能的使用统计
- `/skill validate` - 检查所有技能的格式错误
- `/skill template <type>` - 从预定义模板创建