---
name: expert
version: "2.2.0"
category: expert
description: "当用户明确指定技能名直接调用时使用，支持中英文名称和完整参数控制。不要用于意图不明确时（用 easy）或复杂多技能协作时（用 auto）。Use when user explicitly specifies a skill name (Chinese or English) for direct invocation with full parameter control. Do NOT use when intent is unclear (use easy) or for complex multi-skill orchestration (use auto)."
triggers:
  zh: ["expert", "专家", "完整", "深度", "自定义", "高级", "手动"]
  en: ["expert", "advanced", "full", "deep", "custom", "manual"]
license: MIT
compatibility: Node.js >= 18
metadata:
  author: "sunhongda@example.com"
  created: "2026-06-16"
  updated: "2026-06-18"
  status: "stable"
---

# 专家模式 / Expert Mode

## Changelog / 版本履历

| 日期 | 版本 | 变更摘要 |
|------|------|---------|
| 2026-06-25 | 2.2.0 | **Agent Architecture Integration**: Updated to reference new agent profiles (specialist) instead of hardcoded models, added agent architecture documentation |
| 2026-06-18 | 2.1.0 | **Chinese matching + meta-skill.yaml L1 discovery**: Chinese skill name matching from `meta-skill.yaml` description keywords; L1 (meta-skill.yaml) / L2 (filesystem) discovery priority; alias mapping table; no hardcoding |
| 2026-06-17 | 2.0.0 | **Dynamic discovery**: Replace hardcoded skill references with file-system scanning; normalize YAML/content separators/bilingual headers |
| 2026-06-16 | 1.0.0 | Initial version: basic direct invocation routing |

## Core Concept / 核心概念

### 🇨🇳
一句话说清：输入什么 → 做什么 → 输出什么。明确 **不做什么**。

**输入**: 技能名称 + 参数 | **输出**: 技能执行结果 | **不负责**: 路由决策、意图分析、技能推荐

### 🇺🇸
One line: Input → Process → Output. Explicitly state what is **NOT done**.

**Input**: skill name + parameters | **Output**: skill execution result | **NOT responsible for**: routing decisions, intent analysis, skill recommendations

***

## Agent Architecture Integration / 代理架构集成

The Expert skill integrates with the new agent architecture through **agent profiles** defined in `opespro-opencode-ai.json` and referenced in `meta-skill.yaml`. 

- **Agent Profile**: `specialist` (maps to `livedata/qwen3-coder-plus`)
- **Role**: Domain-specific expertise and implementation
- **Usage**: Expert uses this profile when executing direct skill loading tasks via `task(category="deep", load_skills=["expert"], ...)`

This integration ensures Expert leverages the appropriate model capabilities while maintaining backward compatibility with existing workflows.

***

## Position / 定位

```
User Command → Expert Entry → Direct Skill Load
    (/expert skill-name)        (SKILL.md)
```

Expert is the L0 bypass entry. Unlike `easy` (which routes by keyword) and `auto` (which orchestrates), expert directly loads the specified skill without any routing or intent analysis.

***

## Workflow / 工作流程

### Step 1: Dynamic Discovery / 动态发现

**中文：** Expert 不维护硬编码的技能列表。每次调用时，优先从 `meta-skill.yaml` 协议文件加载技能注册表；若该文件不可用，回退到文件系统扫描动态发现。

**EN:** Expert does NOT maintain a hardcoded skill list. Every invocation dynamically discovers all available skills, **preferring the `meta-skill.yaml` protocol file** as the primary registry; falling back to file-system scanning if unavailable.

**Discovery Priority / 发现优先级**：

| 优先级 | 来源 | 说明 |
|--------|------|------|
| **L1 (Primary)** | `meta-skill.yaml` | 解析 YAML 协议文件，读取所有已注册技能的 `path`、`skill_name`、`description`、`triggers` 等元数据 |
| **L2 (Fallback)** | 文件系统扫描 (`glob` / `find`) | 当 `meta-skill.yaml` 缺失或解析失败时使用，扫描 `*/SKILL.md` 并过滤 L0/非叶子目录 |

**L1: meta-skill.yaml Parsing / 解析 meta-skill.yaml**：
```
1. 读取 skills/meta-skill.yaml 文件
2. 遍历所有领域分组（expert、workflow、quality、tools、meta、auto、easy 等）
3. 提取每个 skill entry 的 `skill_name`、`description`、`triggers`、`path`
4. 构建技能名称索引：skill_name → {path, triggers, description}
5. 从 description 中提取中文关键词 → 构建 alias 映射（详见「中文匹配」章节）
```

**L2: File-System Fallback / 文件系统回退（当 L1 不可用时）**：

**Discovery Pattern / 发现模式**：

```bash
# Find all leaf skill directories (those with their own SKILL.md)
# Exclude L0 entries, docs, config, and non-leaf containers
find . -name "SKILL.md" \
  ! -path "./easy/*" \
  ! -path "./auto/*" \
  ! -path "./expert/*" \
  ! -path "./docs/*" \
  ! -path "./config/*" \
  ! -path "./.omo/*" \
  ! -path "./scripts/*" \
  -type f
```

**Filtering Rules / 过滤规则**：
1. **L0 Exclusions**: Always exclude `easy/`, `auto/`, `expert/` — these are entry points, not leaf skills
2. **Docs/Config Exclusions**: Exclude `docs/`, `config/`, `.omo/`, `scripts/` — these are infrastructure, not skills
3. **Meta Exclusions**: Exclude `meta/` — migrated skills now live at root level

**Using `glob` tool (preferred in OpenCode context)**：
```
glob pattern="*/SKILL.md" — then filter results:
- Keep only paths where the parent directory name != easy, auto, expert
- Extract skill name from directory name
```

### Step 2: Validate Skill Name / 验证技能名称

**中文：** 将用户输入的名称与动态发现的技能列表对比。如果名称不存在，列出 Top 5 最接近的匹配建议。

**EN:** Compare user-provided name against dynamically discovered skill list. If not found, list top 5 closest match suggestions.

**Validation Logic / 验证逻辑**：
```
1. Normalize input: lowercase, trim whitespace
2. Check against discovered skill names (exact match first)
3. If no exact match: fuzzy match (Levenshtein distance, substring match)
4. If no match at all: suggest running auto or easy instead
```

### Step 3: Direct Load / 直接加载

**中文：** 加载已验证的技能的 SKILL.md 指令，直接执行。

**EN:** Load the verified skill's SKILL.md instructions and execute directly.

### Step 4: Report Missing / 报告缺失

**中文：** 如果技能未找到，输出动态发现的可用技能列表及最接近的匹配建议。

**EN:** If skill not found, output dynamically discovered available skill list and closest match suggestions.

### Step 5: Chinese Name Matching / 中文名称匹配

**中文：** Expert 支持使用中文技能名称进行调用。中文名称到技能标识符的映射**不硬编码**，而是从 `meta-skill.yaml` 中各技能的 `description` 字段动态提取中文关键词生成。

**EN:** Expert supports invocation using Chinese skill names. The mapping from Chinese names to skill identifiers is **NOT hardcoded** — it is dynamically generated by extracting Chinese keywords from each skill's `description` field in `meta-skill.yaml`.

**Matching Algorithm / 匹配算法**：

```
输入: "/expert 代码审查"

1. 解析用户输入的中文名称（"代码审查"）
2. 遍历 meta-skill.yaml 中所有已注册技能的 description 字段
3. 提取各 description 的中文部分中的关键名词短语：
   - code-review:    "当用户请求代码审查时使用"  → 关键词: "代码审查"
   - security-check: "当用户请求安全审计时使用"  → 关键词: "安全审计"
   - bug-fixer:      "当用户报告Bug、错误、功能异常或需要调试时使用" → 关键词: "Bug修复"
4. 进行精确匹配或模糊匹配（与英文名称使用相同算法）
5. 匹配成功 → 直接加载目标技能（如 code-review/SKILL.md）
```

**Alias Mapping / 别名映射示例（从 meta-skill.yaml 动态生成）**：

| 中文输入 | 匹配来源（description 中的关键词） | 目标技能 |
|----------|----------------------------------|----------|
| `代码审查` | code-review description: `当用户请求**代码审查**时使用` | `code-review` |
| `安全检查` | security-check description: `当用户请求**安全审计**时使用` | `security-check` |
| `API设计` | api-design description: `当用户需要 **RESTful API 设计**时使用` | `api-design` |
| `Bug修复` | bug-fixer description: `当用户报告**Bug**、错误、功能异常或需要调试时使用` | `bug-fixer` |
| `依赖检查` | deps-check description: `当用户**检查依赖**时使用` | `deps-check` |
| `数据库设计` | db-query description: `当用户需要进行**数据库设计**时使用` | `db-query` |
| `重构设计` | refactor-plan description: `当用户需要**重构设计**时使用` | `refactor-plan` |
| `Vue组件` | vue-component description: `当用户需要 **Vue 2 组件开发**时使用` | `vue-component` |
| `BPM流程` | bpm-workflow description: `当用户需要 **BPM 审批流程设计**时使用` | `bpm-workflow` |
| `环境检查` | env-validator description: `当用户需要**环境验证**时使用` | `env-validator` |
| `代码规范` | linter-expert description: `当用户需要**代码静态检查**时使用` | `linter-expert` |
| `批量重命名` | batch-rename description: `当用户需要**批量重命名文件**时使用` | `batch-rename` |

> ⚠️ **关键原则**：上表仅为示例，映射关系**不硬编码在 Expert 中**。实际运行时，alias 映射完全从 `meta-skill.yaml` 的 `description` 字段动态生成。当新技能注册或 description 更新时，映射自动生效，无需修改 Expert。

**Interactive Examples / 交互示例**：
```
/expert 代码审查 --scope src/   → 匹配 code-review，加载 code-review/SKILL.md
/expert 安全检查                  → 匹配 security-check，加载 security-check/SKILL.md
/expert API设计                  → 匹配 api-design，加载 api-design/SKILL.md
/expert 数据库设计                → 匹配 db-query，加载 db-query/SKILL.md
/expert 前端组件                  → 模糊匹配 → 提示: "Did you mean `vue-component` (Vue组件)?"
```

***

## Dynamic Discovery Reference / 动态发现参考

### Skill Discovery Command (for AI agents)

When expert is invoked, the AI should run ONE of the following to discover available skills:

**Option A: glob (preferred)**
```
glob pattern="*/SKILL.md"
```

**Option B: bash**
```bash
find . -maxdepth 2 -name "SKILL.md" -type f | sort
```

**Post-Discovery Filtering (apply after glob/bash)**:
```
Filters to apply in code:
1. Exclude: ./easy/SKILL.md, ./auto/SKILL.md, ./expert/SKILL.md (L0 entries)
2. Exclude: ./docs/* (documentation, not a skill)
3. Extract skill name = basename of parent directory
```

### Skill Name Resolution Table

| User Input | Resolution | Example Path |
|------------|-----------|-------------|
| `security-check` | Exact match → direct load | `security-check/SKILL.md` |
| `code-review` | Exact match → direct load | `code-review/SKILL.md` |
| `git-safe` | Exact match → direct load | `git-safe/SKILL.md` |
| `ba` | Exact match → direct load | `ba/SKILL.md` |
| `代码审查` | 🇨🇳 Chinese match → `code-review` | `code-review/SKILL.md` |
| `安全检查` | 🇨🇳 Chinese match → `security-check` | `security-check/SKILL.md` |
| `API设计` | 🇨🇳 Chinese match → `api-design` | `api-design/SKILL.md` |
| `sec-check` | Fuzzy → suggest `security-check` | N/A |
| `auto` | ❌ Reject: L0 entry, not a leaf skill | Use `/auto` directly |

***

## Iron Law / 核心铁律

### 🇨🇳
1. **铁律1**: 永不维护硬编码技能列表。优先从 `meta-skill.yaml` 协议文件加载，fallback 到文件系统扫描。违规示例：❌ 在代码中写死 `["security-check", "code-review", ...]`。合规示例：✅ 解析 `meta-skill.yaml` 动态构建技能索引，或使用 `glob pattern="*/SKILL.md"` 回退发现。
2. **铁律2**: 永远不要路由或解释用户意图 - 直接转到指定的技能。违规示例：❌ 尝试猜测用户想要什么技能。合规示例：✅ 严格按照用户输入的技能名称执行。
3. **铁律3**: 在加载技能前验证技能名称是否存在。违规示例：❌ 加载不存在的技能导致错误。合规示例：✅ 检查动态发现的技能列表，确认技能存在后再加载。
4. **铁律4**: 完全按照用户指定的方式传递参数。违规示例：❌ 修改或过滤用户提供的参数。合规示例：✅ 原样传递所有参数给目标技能。

### 🇺🇸
1. **Law 1**: NEVER maintain a hardcoded skill list. Prefer loading from `meta-skill.yaml` protocol file, fallback to file-system scanning. Violation: ❌ Hardcoding `["security-check", "code-review", ...]` in code. Compliance: ✅ Parsing `meta-skill.yaml` to build dynamic skill index, or using `glob pattern="*/SKILL.md"` as fallback.
2. **Law 2**: Never route or interpret user intent - go directly to the specified skill. Violation: ❌ Trying to guess what skill the user wants. Compliance: ✅ Execute exactly the skill name provided by the user.
3. **Law 3**: Validate that the skill name exists before loading. Violation: ❌ Loading a non-existent skill causing errors. Compliance: ✅ Check the dynamically discovered skill list and confirm the skill exists before loading.
4. **Law 4**: Pass parameters exactly as specified by the user. Violation: ❌ Modifying or filtering user-provided parameters. Compliance: ✅ Pass all parameters unchanged to the target skill.

***

## Rationalization Table / 合理化防御表

| # | Trap / 陷阱 | Question / 请问自己 | Action / 应该怎么做 |
|---|-------------|------------------|------------------|
| 1 | "the skill name looks wrong, let me route them to a different skill" | 用户明确指定了技能名称，我为什么要改变它？ | 使用用户输入的确切技能名称，不要尝试纠正或重定向 |
| 2 | "I should interpret their intent and choose the best skill" | Expert入口的设计目的就是绕过意图分析，为什么要违背设计原则？ | 严格按照Expert模式工作：直接加载指定技能，不进行任何路由 |
| 3 | "I'll just remember the skill list instead of scanning" | meta-skill.yaml 协议文件比记忆更可靠，为什么选择更差的方法？ | 每次调用都解析 meta-skill.yaml 或执行文件系统扫描，确保不会遗漏新增或删除的技能 |
| 4 | "The user gave me a partial name, I should try to complete it" | 部分名称是否可能是有效的技能名称？ | 先进行精确匹配；如果失败，列出动态发现的最接近匹配供用户选择 |

***

## Red Flags / 三层防御

### Layer 1: Input / 输入
- **INPUT-01**: 技能名称（中文或英文）在动态发现的列表中未找到 → 🔴 CRITICAL → 列出 Top 5 最接近的匹配建议（含中文别名），或建议使用 `/easy` 进行意图路由
- **INPUT-02**: 用户输入的技能名是 L0 入口（easy/auto/expert） → 🔴 CRITICAL → 提示应直接使用 `/easy`、`/auto` 或 `/expert` 命令，不要通过 expert 代理

### Layer 2: Execution / 执行
- **EXEC-01**: 技能已加载但参数无效 → 🔴 CRITICAL → 报告参数错误并显示正确用法
- **EXEC-02**: meta-skill.yaml 缺失且文件系统扫描失败（权限错误等） → 🔴 CRITICAL → 报告错误并使用上一次缓存的技能列表作为后备

### Layer 3: Output / 输出
- **OUTPUT-01**: 执行结果格式与预期不符 → 🟡 WARN → 继续执行但标记格式问题
- **OUTPUT-02**: meta-skill.yaml 中注册的技能数量异常（<3 或 >50） → 🟡 WARN → 标记异常并确认文件完整性

**级别标识**: 🔴 CRITICAL → 中断 | 🟡 WARN → 继续+标记 | 🔵 INFO → 记录

***

## Output / 输出规范

### 🇨🇳
Expert 入口本身不产生输出——它将执行委托给目标技能，然后由目标技能按照其自身规范产生标准输出。

如果技能未找到，输出：
1. 用户输入的名称
2. 动态发现的可用技能列表
3. 最接近的匹配建议（Top 5）
4. 使用 `/easy` 进行意图路由的建议

### 🇺🇸
Expert entry itself produces no output — it delegates execution to the target skill, which then produces its standard output according to that skill's specifications.

If skill not found, output:
1. User-provided name
2. Dynamically discovered available skill list
3. Closest match suggestions (Top 5)
4. Suggestion to use `/easy` for intent-based routing

***

## Usage / 使用方式

### Invocation / 调用方式

```bash
/expert <skill-name> [options]
```

### Discovery-Validated Examples

```
/expert security-check              → Direct load security-check/SKILL.md
/expert code-review --scope src/    → Direct load code-review/SKILL.md with scope
/expert git-safe                    → Direct load git-safe/SKILL.md
/expert ba                          → Direct load ba/SKILL.md
/expert env-validator               → Direct load env-validator/SKILL.md
/expert 代码审查 --scope src/       → 🇨🇳 Chinese match → code-review/SKILL.md
/expert 安全检查                    → 🇨🇳 Chinese match → security-check/SKILL.md
/expert API设计                     → 🇨🇳 Chinese match → api-design/SKILL.md
```

### What Expert Does NOT Handle

- ❌ `sec-chk` (partial name) → Suggest: "Did you mean `security-check`? Available: security-check, code-review, ..."
- ❌ `auto` (L0 entry) → Reject: "`auto` is an L0 entry point. Use `/auto` directly."
- ❌ "help me with security" (intent-based) → Redirect: "Expert requires an exact skill name. Try `/easy help me with security` for intent-based routing."

***

## Auto-Review / 自检清单

| # | 检查项 |
|---|--------|
| 1 | Skill name is validated against dynamically discovered list |
| 2 | Dynamic discovery was performed (meta-skill.yaml parsed or file-system fallback, not cached/hardcoded) |
| 3 | L0 entries (easy/auto/expert) are properly rejected |
| 4 | Parameters are properly parsed and passed to target skill |
| 5 | Target skill executes without routing errors |
| 6 | No hardcoded skill references exist in logic |