Skills、MCP 与角色
把反复使用的工作方法、外部工具和项目约定分别配置好。任务开始时,Mica 就能找到适合当前工作的指南与能力。
选择扩展方式
| 方式 | 适合放什么 | 配置入口 |
|---|---|---|
| Skills | 按任务读取的审查清单、发布步骤、框架指南。 | 包含 SKILL.md 的目录。 |
| MCP | 文档检索、数据库或团队服务提供的工具。 | config.json 中的 mcpServers。 |
| 角色 | 贯穿会话的工作方式,例如审查者或规划者。 | 用户数据目录中的 role/*.md。 |
| 项目指令 | 项目通用的构建方式、目录职责与验证要求。 | 当前工作目录中的 AGENT.md、AGENTS.md。 |
若要管理带工具、命令或自动行为的完整功能,见 插件与能力管理。 把这些扩展用于一次真实任务的方式,见 日常开发流程。
添加一个 Skill
在当前项目创建 .mica/skills/review-checklist/,将下面内容保存为其中的 SKILL.md。 名称用于识别指南,说明与使用场景帮助模型判断何时读取它:
---
name: review-checklist
description: 审查代码改动,检查正确性、边界情况与测试覆盖
when_to_use: 用户要求审查代码或准备合并改动时
argument-hint: [文件或目录]
---
先阅读项目指令与相关代码,再检查本次 diff。
优先报告可以定位到文件和行的实际问题,并说明触发条件与影响。
检查已有测试是否覆盖行为变化,给出必要的验证建议。
没有发现问题时说明审查范围与尚未验证的部分。终端执行 /skills 可重新扫描并检查发现的 Skills。然后提出请求:“使用 review-checklist 审查本次改动,先报告问题。” 桌面对话输入框支持用斜杠补全选择 Skill,把其文件链接插入请求。
模型通常先看到 Skills 的名称与说明索引,再通过 skill 工具按需读取全文。 Skill 是任务指南,其中的脚本、模板或参考文件仍需在任务中实际读取或执行。
Skill 查找位置
- 项目级:当前工作目录下的
.mica/skills、.agents/skills、.deveco/skills与.agent_context/skills。 - 用户级:
~/.mica/skills,设置MICA_HOME后使用$MICA_HOME/skills。 - 共享目录:未设置
MICA_HOME时,还会扫描~/.agents/skills与~/.config/deveco/skills。
插件也可以附带 Skills,与磁盘发现的指南一起供会话使用;磁盘中的同名 Skill 优先于插件注册的版本。 设置独立的 MICA_HOME 可以隔离个人目录,项目中的 Skills 仍会被发现。
让指南容易被选中与执行
将一个 Skill 聚焦在一种工作上,正文写清输入、步骤、验证方法和交付要求。较长的背景材料放入旁边的参考文件,并说明何时阅读。 若包含脚本,写明依赖、运行目录与会改变的状态,避免让模型猜测执行前提。
Skill 内容不能覆盖系统指令或当前用户要求。若补全或调用中找不到它,先检查文件名、目录与名称,再确认该 Skill 没有被当前会话的能力开关关闭。
连接 MCP 工具
MCP 用于连接提供工具的外部服务。在 ~/.mica/config.json 或 $MICA_HOME/config.json 中添加 mcpServers,保留已有 provider 与其他字段。 服务器名称由你定义,Mica 会在启动时连接并发现工具。
本地进程:stdio
下面使用 Node.js/npm 提供的 npx 启动 Sequential Thinking 服务。先确保启动 Mica 的环境可以找到该命令:
{
"mcpServers": {
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}
}
}本地服务支持 command、args、env、cwd 与 stderr 字段。 服务器自己的依赖、工作目录与凭证要求,应按该服务的说明准备。
远程服务:Streamable HTTP
将示例地址换成服务提供的 MCP 端点。需要认证时可在 headers 中提供请求头,例如从环境变量读取 token:
{
"mcpServers": {
"team-tools": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${TEAM_MCP_TOKEN}"
}
}
}
}启动 Mica 的环境需要设置 TEAM_MCP_TOKEN。url 与 headers 支持 ${VAR} 和 ${VAR:-默认值} 展开;command、args 与 env 中的占位符不由 Mica 展开。
普通网页或 REST API 地址不能直接作为 MCP 服务。应使用服务明确提供的 MCP URL,并确认请求头与传输方式符合服务说明。
检查连接与重连
更新配置并重开会话后,在终端用 /mcp 查看服务器与工具;需要重连时执行 /mcp reconnect sequential-thinking。 本地命令不存在、认证失败或工具发现超时,都应先根据连接错误修正配置。
自动化任务可以使用独立 MCP 文件,明确这次运行要接入的服务:
mica exec --mcp-config ./mcp.json --strict-mcp-config --mcp-init-timeout-ms 10000 "使用可用工具检查服务状态"mcp.json 采用相同的 mcpServers 结构。不传 --strict-mcp-config 时会合并本地配置,同名项以显式文件为准。 超时限制覆盖单个服务的连接与工具发现。更多脚本用法见 自动化与协议。
在能力设置中可以按 MCP 服务器关闭其工具;桌面端为会话接入的受控浏览器与终端也会出现在对应目录中。 默认开关和会话覆盖的区别见 能力管理。
定义角色
将 Markdown 文件放入 ~/.mica/role/ 或 $MICA_HOME/role/,文件名就是角色名。 例如把下面内容保存为 reviewer.md,定义审查任务中的关注点与输出方式:
你是一名代码审查者。
先理解修改目标,再检查正确性、边界情况与回归风险。
每个发现都给出文件位置、触发条件和具体影响。
任务要求只读审查时,保持只读;需要修改时先说明原因与范围。自定义角色与插件提供的角色都会追加到只读的默认正文之后,同属系统提示词,不替换通用约束;项目指令与其他适用规则仍会载入。 终端使用 /role 选择,空闲时也可用 Shift+Tab 循环切换;桌面端从输入区角色入口选择。
mica exec --role reviewer "审查当前工作区的改动,给出可定位的问题"只加载 .md 文件。内置 default 角色在 Role 页面展示默认正文,只读、不可编辑或删除,用户的 default.md 不会覆盖它;选中 default 时不重复追加正文。 角色描述用于指导模型行为,文件权限与可用工具仍需通过对应机制管理。
让项目约定随仓库共享
将适用于所有任务的约定写入当前工作目录的 AGENT.md 或 AGENTS.md;两者存在时都会载入。 记录真实可用的构建与测试命令、模块边界和交付标准,并随代码变化维护。
项目指令保持简短稳定;专项长流程放进 Skill,个人工作风格放进角色,跨会话经验由 Memory 管理。 长任务中的笔记、压缩和协作安排见 日常开发流程;终端操作参考见 命令与快捷键。