Multica Skill

A Claude/AI-agent skill that makes the Multica CLI (multica) a first-class operator — an agent-native issue tracker and workspace CLI.

It covers the full surface of the multica command: issues, agents, autopilots, projects, squads, labels, skills, runtimes, workspaces, repos, the local daemon, attachments, and CLI config/auth.

Installation

Claude Code (recommended)

/plugin install chouti/multica-skill

Other AI agents

skills.sh:

npx skills add chouti/multica-skill

Codex:

install-skill-from-github.py --repo chouti/multica-skill

Cursor:

# Copy to Cursor skills directory
mkdir -p ~/.cursor/skills/multica-skill
cp -R ./* ~/.cursor/skills/multica-skill/

Or copy the Cursor rule to your project's .cursor/rules/ directory.

Manual installation: Copy this repository into your agent's skills directory.

What it does

Once installed, the skill triggers whenever your task involves Multica and helps the agent:

• Issues — create, list, search, update, assign, change status, comment, label, subscribe, set metadata, manage sub-issues, and rerun/cancel tasks.
• Agents — create and update agents, assign skills, manage env vars and MCP config, archive/restore.
• Autopilots — create scheduled or webhook-triggered automations and manage their triggers.
• Projects / Squads / Labels — full CRUD plus project resources and squad membership.
• Runtimes — manage runtimes and custom runtime profiles.
• Workspaces / Auth / Config — switch workspaces, invite members, set CLI config, check auth status, manage user profile.
• Attachments — download attachments to local files.
• Daemon — control the local agent runtime daemon and inspect disk usage.

Design

Progressive disclosure

The skill uses progressive disclosure: a lean SKILL.md carries the trigger logic, global conventions, name-resolution strategy, and multi-step workflow examples, while detailed per-domain command references live in references/ and are read only when needed.

multica-skill/
├── SKILL.md              # trigger logic + conventions + workflows
├── references/           # per-domain command references
│   ├── issues.md
│   ├── agents.md
│   ├── autopilots.md
│   ├── projects.md
│   ├── squads.md
│   ├── labels.md
│   ├── skills.md
│   ├── runtimes.md
│   ├── workspaces.md
│   ├── repos.md
│   ├── daemon.md
│   ├── chat.md
│   └── attachments-cli-global.md
├── .claude-plugin/       # Claude Code plugin metadata
│   └── plugin.json
└── .cursor/rules/        # Cursor agent rules
    └── multica-cli.mdc

Safety-first

The skill emphasizes read before write and confirm before side effects:

• Always read issue context before making changes
• Confirm with user before posting comments, changing status, or mentioning agents
• Use --content-file for comments (never inline) to avoid shell escaping issues
• Explicit warnings about mention side effects and status transitions

See EXAMPLES.md for concrete usage scenarios.

Visual aids and decision support

Unlike basic command references, this skill provides visual decision aids to help agents make better choices:

• Quick Decision Trees — instant lookup for common tasks (read issue, create bug, reply to comment, mention safely)
• Mention Decision Tree — visual guide to avoid accidentally triggering agent work
• Status State Machine — ASCII diagram showing how status transitions trigger (or don't trigger) agent runs
• Status Transition Matrix — risk levels and recommended actions for every status change
• Stage Patterns Library — 4 complete patterns (Sequential, Parallel, Gated, Investigation→Action) with code examples

Comprehensive templates

Ready-to-use templates for common scenarios:

• Metadata Templates — Bug, Feature, Integration, and Decision issue templates with recommended keys
• Metadata Anti-Patterns — clear guidelines on what belongs in metadata vs comments/description
• External Agent Pre-Flight Checklist — 17-item verification checklist before working on issues
• Common Pitfalls — 7 critical mistakes agents make and how to avoid them

Complete troubleshooting

A full Troubleshooting Guide covering 7 categories of issues:

1. Authentication issues (login, token expiry, profile setup)
2. Name resolution (ambiguous names, missing entities, UUID lookup)
3. Command execution (404 errors, permission issues, shell escaping)
4. Mention and side effects (accidental triggers, status change warnings)
5. Metadata management (persistence, cleanup, read-only fields)
6. Workspace and profile issues (wrong workspace, profile configuration)
7. Pull Request integration (linking issues, close intents)

Plus 7 general debugging tips for when things go wrong.

Key behaviors

• Name resolution — tries the literal name the user gave first, resolves via list commands only on failure, and never silently substitutes an unrelated UUID.
• Safe multi-line input — always uses --content-file / --*-stdin / --*-file flags to avoid shell-escaping issues.
• JSON-first — uses --output json internally, renders a human summary at the end.
• Mention awareness — understands that @agent mentions can enqueue work, warns about unintended triggers.
• Decision trees — provides visual guides for common decisions (mention syntax, status changes, stage patterns).
• Template-driven — offers ready-to-use metadata templates for bug/feature/integration/decision issues.
• Troubleshooting-ready — includes solutions for authentication, name resolution, commands, mentions, metadata, workspace, and PR integration issues.

What makes this skill special

This skill goes beyond basic command coverage:

• 3.3x more comprehensive than the official Multica CLI skill (803 vs 242 lines)
• Progressive disclosure architecture — lean SKILL.md with 13 detailed reference files
• Visual decision aids — state machines, transition matrices, decision trees
• Template library — metadata templates for common issue types
• Complete troubleshooting — solutions for 7 categories of common problems
• Safety-first design — explicit warnings, confirmation prompts, side effect documentation

Prerequisites

• The multica CLI installed and authenticated (multica auth status should succeed).
• A default workspace selected (multica workspace switch <id>).

Compatibility

Works with Claude Code and other AI coding agents that support the skills format.

Acknowledgments

This skill was inspired by and built upon the best practices from the official Multica CLI skill by the Multica team. We are grateful for their foundational work on:

• Safety-first design — read before write, confirm before side effects
• Mention syntax documentation — structured mention links and side effect warnings
• Status transition awareness — understanding how status changes trigger agent work
• Metadata best practices — durable state vs ephemeral logs
• External agent boundaries — permission verification and context requirements
• Multi-agent support — Claude Code plugins, Cursor rules, and Codex compatibility

We took their excellent foundation and enhanced it with comprehensive command coverage, visual decision aids, template libraries, and a complete troubleshooting guide. Our goal was to create the most complete and user-friendly Multica CLI skill possible, while building on the solid best practices established by the Multica team.

Thank you to the Multica team for their pioneering work in agent-native issue tracking! 🙏

License

MIT — see LICENSE.