Skills

Skills 模块：一步一步教程

把 skills 当作可复用执行规范，并绑定到 agent，形成稳定、可回归的行为。

步骤 1：查看当前 skill 清单

mosaic --project-state skills list
mosaic --project-state skills list --source all
mosaic --project-state skills list --source project

预期：你能区分 project 与 user/global 来源。

步骤 2：创建最小可用 skill 包

mkdir -p ./writer
cat > ./writer/SKILL.md <<'EOF'
# Writer
Produce concise, structured answers.

## Rules
- Start with the direct answer.
- Keep examples short.
EOF

预期：本地目录有非空 SKILL.md 且包含标题。

步骤 3：安装并检查 skill

mosaic --project-state skills install --path ./writer
mosaic --project-state skills info writer
mosaic --project-state skills check writer

如需覆盖安装，追加 --force。

步骤 4：把 skill 绑定到 agent

# 创建新 agent 并绑定 skill
mosaic --project-state agents add \
  --name Writer \
  --id writer \
  --skill writer \
  --set-default \
  --route ask

# 或更新已有 agent
mosaic --project-state agents update writer --skill writer
mosaic --project-state agents show writer

预期：agents show writer 中可见 skills: writer。

步骤 5：通过该 agent 执行 ask/chat

mosaic --project-state ask --agent writer "summarize this repository"
mosaic --project-state chat --agent writer

预期：模型回复更稳定地遵循你在 skill 中定义的规范。

步骤 6：在 mock 回归中验证注入

MOSAIC_MOCK_CHAT_RESPONSE=ok \
MOSAIC_MOCK_CHAT_CAPTURE_PATH=./mock-chat-request.json \
mosaic --project-state ask --agent writer "hello"

检查 mock-chat-request.json，确认包含：

• BEGIN AGENT SKILL: writer
• 你的 SKILL.md 内容

步骤 7：更新与替换 skill

# 修改 ./writer/SKILL.md 后重装
mosaic --project-state skills install --path ./writer --force
mosaic --project-state skills check writer

步骤 8：解绑并清理

mosaic --project-state agents update writer --clear-skills
mosaic --project-state skills remove writer
mosaic --project-state skills list --source project

建议先解绑再删除，避免运行时因为缺失 skill 报错。

步骤 9：JSON 契约用于脚本/CI

mosaic --project-state --json skills list
mosaic --project-state --json skills info writer
mosaic --project-state --json skills check writer
mosaic --project-state --json agents update writer --skill writer

步骤 10：排障清单

• skill '<id>' not found：先跑 skills list，并确认状态模式一致（是否都带 --project-state）。
• skills check 失败：确认 SKILL.md 存在、可读、非空、且有标题。
• 看起来未生效：检查 agents show <id> 与路由/默认 agent 解析。
• 删除 skill 后运行失败：重新安装该 skill，或执行 agents update <id> --clear-skills。