Skills

Skills是 Mogick CLI 的核心扩展机制。每一份Skills都是一个 Markdown 文件，其中封装了领域知识、工作流模板和上下文指令。Agent 启动时会自动扫描所有可用Skills目录，当用户任务与某个Skills的描述匹配时，Agent 通过 skill.load 将其注入上下文，使通用模型即时获得专业领域的行为能力。

Skills的设计理念是"即放即用"：无需编译、无需配置、无需重启服务，将 .md 文件放入正确的目录即可生效。

Skills目录与优先级

默认搜索范围包含 Mogick/Agents 目录和产品内置路径。

位置	作用域	覆盖规则
`.mogick/skills/`、`.agents/skills/`	项目/祖先目录	项目与工作区Skills
`<config-dir>/skills/`、`~/.agents/skills/`	用户级	跨项目共享
产品内置路径	产品级	随产品提供
`skills.search_path_extras`	显式扩展	需要继续使用其他目录时手动配置

项目级Skills适合存放团队协作规范、项目特定的代码审查规则或部署流程。用户级Skills则适合个人偏好的快捷指令和私有工作流。

例如显式添加额外路径：

json

{
  "skills": {
    "search_path_extras": ["/absolute/path/to/team-skills"]
  }
}

新建Skills的默认根由 skills.create_root（"mogick" 或 "agents"）和 skills.create_scope（"project" 或 "global"）决定，也可运行 mogick setup skill 交互配置。

Skills文件格式

Skills文件名即为Skills标识符，Agent 通过 YAML 前置元数据中的 description 字段进行语义匹配。一个典型的Skills文件结构如下：

markdown

---
name: code-review
description: 代码审查规范：检查项、报告格式与审批流程
---

# 代码审查规范

1. 检查代码风格是否符合 ESLint 配置
2. 验证类型安全，确保无 `any` 类型逃逸
3. 检查边界条件和错误处理
4. 确认测试覆盖率未下降

前置元数据中 name 是Skills的唯一标识（可选，省略时从文件名推断），description 是对Skills的简短描述，直接影响任务匹配精度。描述写得越具体，Agent 在无关任务中误触发该Skills的概率越低。正文部分使用标准 Markdown 编写，可以包含检查清单、代码模板、决策树或任何有助于 Agent 理解领域规则的文字。

管理Skills

日常Skills管理可通过 TUI 界面或文件操作完成。在 TUI 中输入 /skills 即可查看和加载当前可用的Skills列表及其来源目录。

如需控制Skills的可用性，可通过配置中的 skills.disabled 列表或宿主集成接口管理；TUI /skills 面板用于浏览和加载Skills。

已加载到当前上下文的 Skill 指令不会在会话中途自动替换；修改 Skill 文件后，建议重新打开会话或通过宿主/刷新流程重新加载。Agent 每次启动时会自动重新扫描全部Skills目录，因此新增的Skills文件无需手动注册。

诊断与排错

当Skills行为不符合预期时，使用 doctor 命令检查系统状态：

bash

mogick doctor                    # 默认输出 Markdown 诊断报告
mogick doctor --json             # 切换为 JSON 格式
mogick doctor --export ./report.md  # 导出报告到文件

doctor 默认以 Markdown 格式在终端渲染诊断信息，包括Skills搜索根、解析状态和已加载Skills。使用 mogick doctor --export <路径> 可直接写入文件。如果Skills未加载，先检查 SKILL.md 前置元数据、目录权限以及 skills.search_path_extras 是否指向正确路径。

Skills与 MCP 的关系

Skills和 MCP 是互补机制：Skills提供"怎么做"的知识流程，MCP 提供"用什么做"的工具能力。一份Skills可以指导 Agent 在特定场景下调用哪些 MCP 工具、以何种顺序组合、如何处理异常。内置产品Skills已包含 Syslab 与 Sysplorer 场景的协作规则，用户自定义Skills也可以引用任意已连接的 MCP 服务。

路径占位符 <config-dir>、<db-path> 指当前 profile/通道实际生效的路径，见数据目录。

Skills ​

Skills目录与优先级 ​

Skills文件格式 ​

管理Skills ​

诊断与排错 ​