Skills

Skills Module: Step-by-Step Tutorial

Use skills as reusable execution instructions, then bind them to agents for stable behavior.

Step 1: Inspect current skill inventory

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

Expected: You can see which skills come from project state vs user/global roots.

Step 2: Create a minimal local skill package

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

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

Expected: local path contains a non-empty SKILL.md with headings.

Step 3: Install and inspect the skill

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

Use --force when replacing an existing installation.

Step 4: Bind skill to an agent

# create new agent with skill
mosaic --project-state agents add \
  --name Writer \
  --id writer \
  --skill writer \
  --set-default \
  --route ask

# or update existing agent
mosaic --project-state agents update writer --skill writer
mosaic --project-state agents show writer

Expected: agents show writer includes skills: writer.

Step 5: Run ask/chat through the bound agent

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

Expected: model follows your skill guidance more consistently.

Step 6: Verify prompt injection in mock regression

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

Inspect mock-chat-request.json and confirm it contains:

• BEGIN AGENT SKILL: writer
• Your SKILL.md content

Step 7: Update or replace skill safely

# edit ./writer/SKILL.md, then reinstall
mosaic --project-state skills install --path ./writer --force
mosaic --project-state skills check writer

Step 8: Unbind and remove cleanly

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

Always unbind first to avoid runtime failures on missing skills.

Step 9: JSON contracts for CI/scripts

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

Step 10: Troubleshooting checklist

• skill '<id>' not found: run skills list and verify the same --project-state mode.
• skills check fails: ensure SKILL.md exists, is readable, non-empty, and has a heading.
• Skill seems ignored: check agents show <id> and route/default resolution.
• Runtime fails after removing a skill: reinstall it or run agents update <id> --clear-skills.