Skip to content

SKILL.md

Latest commit

 

History

History
810 lines (602 loc) · 28.1 KB

SKILL.md

File metadata and controls

810 lines (602 loc) · 28.1 KB
Raw
name multica
description Use when the user's goal is one of: - Working with the Multica issue tracker ("multica", "mc issue", "in multica", "file in multica", English/中文/mixed): create, find, search, list, update, assign, label, comment, change status, add subscribers, set/clear metadata, set/clear custom property values, view runs/rerun/cancel. - Managing Multica entities: agents (create, update, archive/restore, skills, env, tasks), autopilots (with schedule or webhook triggers), projects + project resources, squads + squad members, workspace labels, workspace skills + skill files, runtimes (incl. rename), workspaces/auth/config/user profile, workspace custom issue property definitions, repo registry, local daemon (start/stop/status/disk-usage). - Operational tooling: download or upload attachments, check/refresh `multica auth status`, manage CLI profiles, run `multica update` to self-upgrade. Language-agnostic — handles English, 中文 (e.g. "建 issue", "改状态", "加 schedule", "分配给"), and mixed English/中文 queries. Do NOT trigger for other issue trackers (GitHub, GitLab, Jira, Linear, Shortcut) — use their dedicated skills instead.

Multica

This skill makes Claude a capable operator for the Multica CLI (multica).

When to use this skill

  • Create, find, update, assign, label, comment on, or change the status of a Multica issue.
  • Manage Multica agents, autopilots, projects, squads, labels, skills, runtimes, workspaces, repos, or the daemon.
  • Download attachments, manage CLI config/profiles, or check multica auth status.
  • The user says anything like "multica", "mc issue", "in Multica", "file this in multica".

When NOT to use this skill

  • The task is about a different issue tracker (GitHub, GitLab, Jira, Linear).
  • The task is purely local file management with no Multica context.

Quick reference map

Read only the reference file relevant to the current task. Do not read all references at once; most tasks need only one.

User goal Read this reference
Issues (create, list, search, update, assign, status, comments, labels, subscribers, metadata, sub-issues, rerun/cancel) references/issues.md
Agents (create, update, skills, env, archive/restore) references/agents.md
Autopilots and triggers references/autopilots.md
Projects and project resources references/projects.md
Squads and squad members references/squads.md
Workspace labels references/labels.md
Workspace skills and skill files references/skills.md
Runtimes and runtime profiles references/runtimes.md
Auth, workspace, config, user profile references/workspaces.md
Repo registry references/repos.md
Daemon control and disk usage references/daemon.md
Chat history/thread context references/chat.md
Attachments, CLI version/update, global flags references/attachments-cli-global.md

If the task spans multiple domains, read the references in dependency order (e.g. read issues.md first, then labels.md only if you need to create or attach labels).

Quick Decision Trees

"I need to..."

...read an issue → multica issue get <id> --output json

...create a bug → See "Multi-step workflows: File a bug"

...reply to a comment → See "Write Workflow: Comments"

...mention someone without triggering work → Use [@Name](mention://member/<id>) or plain text

...mention an agent to trigger work → Use [@Name](mention://agent/<id>) and confirm with user

...check if my change will trigger work → See "Status Transition Matrix" and "Mention Decision Tree"

...troubleshoot a command failure → See "Troubleshooting" section below

Core Safety Rules

1. Read Before Write

Always gather context before making changes:

# Read issue first
multica issue get <id> --output json

# Read comments
multica issue comment list <id> --limit 10 --output json

# Read metadata
multica issue metadata get <id> --output json

2. Confirm Before Side Effects

These operations require user confirmation:

  • Posting comments (especially with @mentions)
  • Changing status (open → closed, in_progress → done, etc.)
  • Assigning issues
  • Creating autopilots
  • Any write operation

Why? These can trigger agent work, notifications, or workflow automation.

3. Use Files for Content (Never Inline)

Wrong ❌:

multica issue comment add 123 --content "Here is the fix..."

Right ✅:

cat > reply.md << 'EOF'
Here is the fix...
EOF

multica issue comment add 123 --content-file reply.md
rm reply.md

Why? Shells rewrite backticks, $(), quotes, and newlines in inline content.

4. Mention Side Effects

⚠️ Mentions trigger agent work!

Multica uses structured mention syntax. Only agent and squad mentions enqueue work:

[@Agent Name](mention://agent/<agent-id>)    # Enqueues that agent
[@Squad Name](mention://squad/<squad-id>)    # Enqueues the squad leader
[@User Name](mention://member/<user-id>)     # Just a person link (no work)
[MUL-123](mention://issue/<issue-id>)        # Just an issue link (no work)
[@all](mention://all/all)                    # Broadcast (no specific agent run)

Mention Decision Tree

Want to trigger work?
├─ Yes → Use agent/squad mention
│  ├─ Single agent → [@Name](mention://agent/<id>)
│  └─ Team lead → [@Name](mention://squad/<id>)
└─ No → Use member/issue mention or plain text
   ├─ Person link → [@Name](mention://member/<id>)
   ├─ Issue link → [MUL-123](mention://issue/<id>)
   └─ Just mention → "Thanks to the backend team!" (no syntax)

Common Mention Mistakes

❌ Wrong: Thanks [@backend-agent](mention://agent/xxx) for the help!

  • This triggers another agent run and creates loops!

✅ Right: Thanks to the backend team for the help!

  • No mention syntax = no trigger

❌ Wrong: @backend-agent please review

  • Plain @ doesn't work in Multica

✅ Right: [@backend-agent](mention://agent/<id>) please review

  • Use proper mention syntax

Always warn the user before posting a comment with agent/squad mentions:

"Warning: This comment mentions @backend-agent, which will enqueue work for that agent. Continue?"

Important: Do not mention an agent just to thank, acknowledge, or sign off. Re-mentioning an agent in a reply can trigger another run and create loops.

Look up real UUIDs with JSON output before constructing mentions:

multica agent list --output json
multica squad list --output json
multica workspace member list --output json

5. Status and Assignment Side Effects

Status changes are not cosmetic — they can enqueue or stop work:

  • backlog — parks an agent-assigned issue (pauses work)
  • Moving from backlog to todo or another active status — can enqueue the assignee
  • done and cancelled — terminal states (stops work)
  • in_review — useful while a PR or human review is pending, but still a write

Always confirm status changes with the user before executing.

Status State Machine

         ┌─────────────┐
         │   backlog   │ ← Parks agent work
         └──────┬──────┘
                │ move to active
                ▼
    ┌───────────────────────┐
    │                       │
┌───▼────┐  ┌──────────────▼────┐
│  todo  │  │   in_progress     │ ← Agent working
└───┬────┘  └──────────────┬────┘
    │                      │
    │                      ▼
    │              ┌───────────────┐
    └──────────────►   in_review   │ ← Waiting for PR/review
                   └───────┬───────┘
                           │
                           ▼
                   ┌───────────────┐
                   │     done      │ ← Terminal
                   └───────────────┘

Status Transition Matrix

From → To Side Effect Risk Level Action
backlog → todo Triggers assignee ⚠️ Medium Confirm first
backlog → in_progress Triggers assignee ⚠️ Medium Confirm first
todo → in_progress None ✅ Low Safe
in_progress → in_review None ✅ Low Safe
in_review → done Stops agent ✅ Low Safe
in_review → in_progress None ✅ Low Safe
Any → cancelled Stops agent ⚠️ High Always confirm
Any → backlog Parks agent ⚠️ Medium Confirm first

6. Sub-Issues and Stages

For ordered work (e.g., research → build → test), use parent issues with stages and backlog for later steps:

# Create research task (stage 1, active)
multica issue create --title "Research OAuth flow" --parent <parent-id> --assignee <agent> --stage 1 --status todo

# Create build task (stage 2, parked)
multica issue create --title "Implement OAuth fix" --parent <parent-id> --assignee <agent> --stage 2 --status backlog

# View sub-issues
multica issue children <parent-id> --output json

Stages ensure ordered execution: stage 2 won't start until stage 1 is done.

Stage Patterns Library

Pattern 1: Sequential (Waterfall)

Research (stage 1, todo) → Build (stage 2, backlog) → Test (stage 3, backlog)

multica issue create --title "Research" --stage 1 --status todo
multica issue create --title "Build" --stage 2 --status backlog
multica issue create --title "Test" --stage 3 --status backlog

Use when: Tasks must complete in strict order

Pattern 2: Parallel Development

Design (stage 1) → [Frontend (stage 2) ‖ Backend (stage 2)] → Integration (stage 3)

multica issue create --title "Design" --stage 1 --status todo
multica issue create --title "Frontend" --stage 2 --status backlog
multica issue create --title "Backend" --stage 2 --status backlog
multica issue create --title "Integration" --stage 3 --status backlog

Use when: Independent tasks can run in parallel after a prerequisite

Pattern 3: Gated Release

Dev (stage 1) → QA (stage 2) → Staging (stage 3) → Production (stage 4)

Use when: Each stage requires approval before proceeding

Pattern 4: Investigation → Action

Investigate (stage 1, todo) → [Fix (stage 2, backlog) ‖ Document (stage 2, backlog)]

Use when: Need to understand before acting, then multiple actions possible

Stage Rules

  1. Lower stage numbers run first
  2. Same stage can run in parallel (multiple issues with same stage number)
  3. Stage N starts only when all stage N-1 issues are done
  4. Use backlog status for stages that shouldn't auto-start
  5. Use todo status for the first stage you want to start immediately

Prerequisites

  • multica CLI must be installed and authenticated (multica auth status should show success).
  • A default workspace should be selected (multica workspace list then multica workspace switch <id> if needed).
  • Most multica commands accept --output json; prefer JSON for programmatic parsing.

Global CLI conventions

  • Use --output json when you need structured data.
  • Use --output table when presenting results to the user in a compact form.
  • IDs in Multica can usually be short prefixes; use --full-id when you need full UUIDs.
  • Many flags accept names and do fuzzy matching (e.g. --assignee, --to, --agent, --member).
  • For multi-line text, always use --content-file or --*-stdin / --*-file to avoid shell escaping issues. Never use inline --content for comments or descriptions.
  • Use --profile <name> to work across isolated Multica environments (dev/staging/production).
  • Use --workspace-id <id> or MULTICA_WORKSPACE_ID to override the active workspace per command.

Command Parameter Gotcha

⚠️ Different commands use different parameter names for assignees:

  • issue assign uses --to / --to-id
  • issue create and issue update use --assignee / --assignee-id

Don't mix these up!

Resolving names and ambiguity

Many Multica flags accept names and do fuzzy matching. Follow this order:

  1. Use the name exactly as the user provided it in the first attempt. Do not substitute a UUID unless explicitly asked.
  2. If the CLI returns an error like no member, agent, or squad found matching "...", then resolve the name:
    • multica agent list --output json
    • multica squad list --output json
    • multica workspace member list --output json
  3. If the name still cannot be found, report that to the user and ask for clarification. Do not silently substitute an unrelated UUID.
  4. If the name is ambiguous (multiple matches), present the candidates and ask the user to pick one.

Output formatting for users

When reporting results back to the user:

  1. Summarize what was done in one sentence.
  2. Include the most important identifiers (issue ID, agent ID, project ID, etc.).
  3. For lists, prefer a markdown table with key columns.
  4. Mention any next steps or blockers.

Example:

Created issue ISS-123 in project PROJ-456 with status todo and assigned to backend-agent.

Error handling

  • If multica auth status fails, ask the user to run multica login.
  • If a command returns a 404 or "not found", check whether the ID is a short prefix that has become ambiguous; use --full-id or fetch via list.
  • If a create/update fails because of invalid fields, surface the exact CLI error and suggest the fix.
  • For multi-line text, always use --description-stdin, --content-stdin, --custom-env-stdin, --mcp-config-stdin, etc., to avoid shell escaping issues.

7. Metadata Best Practices

Metadata is durable issue state, not a log. Use it for high-signal facts that future runs will re-read:

Good metadata keys: pr_url, pr_number, pipeline_status, deploy_url, external_issue_url, waiting_on, blocked_reason, decision

Bad metadata usage: Don't use metadata for progress logs, comments, or temporary state.

# Set useful metadata
multica issue metadata set <id> pr_url https://github.com/org/repo/pull/123
multica issue metadata set <id> blocked_reason "Waiting for API credentials"

# Clean up stale metadata
multica issue metadata delete <id> old_key

Read metadata on entry to understand issue state, but only write when you have durable information.

Metadata Templates

Bug Issue Template

multica issue metadata set <id> bug_severity high
multica issue metadata set <id> affected_version 2.3.1
multica issue metadata set <id> fixed_in_version 2.3.2
multica issue metadata set <id> regression_from 2.3.0
multica issue metadata set <id> root_cause "Database connection timeout"

Feature Issue Template

multica issue metadata set <id> feature_priority P1
multica issue metadata set <id> target_release Q2-2024
multica issue metadata set <id> stakeholder product-team
multica issue metadata set <id> spec_url https://docs.google.com/...
multica issue metadata set <id> design_doc_url https://...

Integration Issue Template

multica issue metadata set <id> pr_url https://github.com/...
multica issue metadata set <id> pr_number 456
multica issue metadata set <id> pipeline_status running
multica issue metadata set <id> deploy_url https://staging.example.com
multica issue metadata set <id> test_results passed
multica issue metadata set <id> external_issue_url https://jira.example.com/...

Decision Template

multica issue metadata set <id> decision "Use PostgreSQL over MongoDB"
multica issue metadata set <id> decision_reason "Better ACID compliance"
multica issue metadata set <id> decision_date 2024-01-15
multica issue metadata set <id> decision_by alice

Metadata Anti-Patterns

❌ Don't use metadata for:

  • Progress logs (use comments instead): "Progress: 50% complete"
  • Temporary state (use local variables): "currently_building"
  • Conversations (use comment threads): "Alice said X, Bob replied Y"
  • Debugging notes (use description updates): "Tried approach A, failed"
  • Frequent updates (metadata is for durable facts)

✅ Use metadata for:

  • Durable facts that future runs need: pr_url, deploy_url
  • Cross-system references: external_issue_url, jira_ticket
  • Decision records: decision, decision_reason
  • Status flags: pipeline_status, waiting_on
  • Version tracking: affected_version, fixed_in_version

Rule of thumb: If a future agent run would need this information to continue work, it belongs in metadata. If it's just for human readers, use comments or description.

Pull Request Integration

When code changes are made for a Multica issue, include the routable issue key in your PR to enable automatic linking:

PR title examples:

  • MUL-123: fix OAuth callback redirect
  • Fix OAuth callback (MUL-123)

Use close intent when merging the PR should close the issue:

Closes MUL-123
Fixes MUL-123
Resolves MUL-123

Read linked PR state from Multica rather than guessing from GitHub:

multica issue pull-requests <issue-id> --output json

External Agent Boundaries

External agents don't receive Multica runtime context automatically. Before working on a specific issue or comment, ensure you have:

  • ✅ Issue ID or issue key (e.g., MUL-123)
  • ✅ Trigger comment ID and parent thread (if replying to a comment)
  • ✅ Intended workspace/profile (if more than one is configured)
  • ✅ Whether writes are allowed
  • ✅ Whether mentions, status changes, reruns, or assignments are allowed

If any of these are missing and the operation would write state, ask the user before proceeding. For read-only investigation, gather context with JSON output and report what else is needed.

External Agent Pre-Flight Checklist

Before working on any Multica issue, verify:

Required Information

  • Issue ID or key (e.g., MUL-123)
  • Trigger comment ID (if replying to a specific comment)
  • Parent thread ID (if working within a thread)
  • Target workspace name or ID (if multiple configured)
  • Target profile name (if multiple configured)

Permission Verification

  • User has explicitly allowed reads (usually implicit)
  • User has explicitly allowed writes (if any write operation needed)
  • User has explicitly allowed mentions (if mentioning agents/squads)
  • User has explicitly allowed status changes (if changing status)
  • User has explicitly allowed assignments (if assigning issues)
  • User has explicitly allowed reruns (if rerunning agents)

Context Verification

  • You understand the issue's current state (multica issue get <id>)
  • You understand who is assigned (if anyone)
  • You understand any blockers or dependencies
  • You understand the expected outcome or deliverable
  • You understand the deadline or urgency (if any)

Safety Verification

  • Your operation won't trigger unintended agent work
  • Your operation won't change status without confirmation
  • Your operation won't assign without confirmation
  • You have warned about any mention side effects
  • You have confirmed with user before any write operation

Common External Agent Pitfalls

❌ Assuming you can write → Always ask first, even if user asked you to "fix" something ❌ Assuming single workspace → Check multica workspace list if unsure ❌ Assuming mention is safe → Always warn about side effects ❌ Assuming status change is cosmetic → Always check transition matrix ❌ Assuming you know the context → Always read issue state first ❌ Assuming user wants immediate action → Draft and confirm before posting ❌ Mixing up --to and --assignee → Check command parameter gotcha

✅ Best practice: When in doubt, read first, draft response, show to user, get explicit confirmation, then execute.

Multi-step workflows

When the user's request spans multiple commands, run them in dependency order and report the final state. Prefer JSON output internally and render a human summary at the end.

Example: file a bug, assign it, label it, and add a comment

ISSUE=$(multica issue create \
  --title "OAuth callback fails behind corporate proxy" \
  --description "Users behind corporate proxy cannot complete OAuth flow." \
  --status todo \
  --priority high \
  --output json)
ID=$(echo "$ISSUE" | jq -r '.identifier')

multica issue assign "$ID" --to "backend-squad"
multica issue label add "$ID" "needs-triage"
echo "Investigating proxy redirect handling." | multica issue comment add "$ID" --content-stdin

Example: create a bug, assign it, and label it (minimal)

ISSUE=$(multica issue create --title "..." --description "..." --status todo --output json)
ID=$(echo "$ISSUE" | jq -r '.identifier')
multica issue assign "$ID" --to "backend-squad"
multica issue label add "$ID" "needs-triage"

Example: create an agent, assign skills, and verify it can run

AGENT=$(multica agent create --name "doc-writer" --runtime-id "$RUNTIME_ID" --instructions "..." --model claude-sonnet-4-6 --output json)
AGENT_ID=$(echo "$AGENT" | jq -r '.id')
multica agent skills add "$AGENT_ID" --skill-ids "$SKILL_ID"
multica agent get "$AGENT_ID" --output json

Example: create a daily autopilot

AUTOPILOT=$(multica autopilot create --title "Daily standup summary" --description "..." --agent "standup-agent" --mode create_issue --project "$PROJECT_ID" --output json)
AUTO_ID=$(echo "$AUTOPILOT" | jq -r '.id')
multica autopilot trigger-add "$AUTO_ID" --kind schedule --cron "0 9 * * *" --timezone Asia/Shanghai

Example: resolve a name and then filter

If the user asks for "issues assigned to backend-agent" and you are unsure whether that entity exists:

multica issue list --status in_progress --assignee "backend-agent" --output json

If that fails with "no member, agent, or squad found matching", then:

multica agent list --output json
multica squad list --output json

Report the finding to the user; do not substitute another entity.

Troubleshooting

Common issues and their solutions when working with Multica CLI.

Authentication Issues

Problem: multica auth status fails or reports no active session

# Solution 1: Login interactively
multica login

# Solution 2: Use setup for first-time configuration
multica setup

# Solution 3: Check if you're in the right profile
multica auth status --profile <profile-name>

Problem: Authentication token expired

# Solution: Re-authenticate
multica login

Name Resolution Issues

Problem: "no member, agent, or squad found matching..."

# Solution 1: List available entities
multica agent list --output json
multica squad list --output json
multica workspace member list --output json

# Solution 2: Use exact UUID instead of name
multica issue assign <id> --to-id <exact-uuid>

# Solution 3: Check if name has typos or different casing
# Multica names are case-sensitive in some contexts

Problem: Multiple matches for a name (ambiguous)

# Solution: List all matches and ask user to pick
multica agent list --output json | jq '.[] | select(.name | contains("backend"))'

Command Execution Issues

Problem: Command fails with "404 not found"

# Solution 1: ID is ambiguous (short prefix matches multiple)
# Use --full-id or get full ID
multica issue get <id> --full-id --output json

# Solution 2: ID doesn't exist
# Verify the ID is correct
multica issue list --output json | jq '.[] | select(.identifier == "<id>")'

# Solution 3: Wrong workspace
# Check current workspace
multica workspace get
# Switch if needed
multica workspace switch <workspace-id>

Problem: Command fails with permission error

# Solution 1: Check workspace permissions
multica workspace member list --output json

# Solution 2: Check if you're in the right workspace
multica workspace list --output json

# Solution 3: Some operations require admin/owner role
# Check your role in workspace member list

Problem: Shell escaping issues with multi-line content

# Solution: Always use --content-file or --*-stdin/--*-file
# Never use inline --content for comments or descriptions

# Wrong ❌
multica issue comment add <id> --content "Line 1\nLine 2"

# Right ✅
cat > reply.md << 'EOF'
Line 1
Line 2
EOF
multica issue comment add <id> --content-file reply.md
rm reply.md

Mention and Side Effect Issues

Problem: Mention triggers unexpected agent run

# Problem: Used agent mention syntax accidentally
# Solution: Use plain text without mention syntax

# Wrong ❌ (triggers agent work)
[@backend-agent](mention://agent/xxx) can you review this?

# Right ✅ (no trigger)
Can the backend team review this?

# Or use member mention (no trigger)
[@Backend Agent](mention://member/<user-id>) can you review this?

Problem: Status change triggers unexpected agent work

# Problem: Moved from backlog to active status
# Solution: Check Status Transition Matrix before changing status

# Safe transitions (no trigger):
# todo → in_progress
# in_progress → in_review
# in_review → done

# Dangerous transitions (may trigger):
# backlog → todo (triggers assignee)
# backlog → in_progress (triggers assignee)

# Always confirm with user before dangerous transitions

Metadata Issues

Problem: Metadata not persisting or disappearing

# Solution 1: Check if you're using the right syntax
# Wrong ❌
multica issue metadata set <id> key=value

# Right ✅
multica issue metadata set <id> --key <key> --value <value>

# Solution 2: Check permissions (some metadata is read-only)
multica issue metadata get <id> --output json

Problem: Too much metadata cluttering issue

# Solution: Clean up stale metadata
multica issue metadata list <id> --output json
multica issue metadata delete <id> <stale-key>

# Remember: metadata is for durable facts, not logs
# Use comments for progress updates

Workspace and Profile Issues

Problem: Working in wrong workspace

# Solution 1: List available workspaces
multica workspace list --output json

# Solution 2: Switch to correct workspace
multica workspace switch <workspace-id>

# Solution 3: Use explicit flags per command
multica --workspace-id <workspace-id> issue list --output json

Problem: Profile not configured correctly

# Solution 1: List available profiles
multica config show

# Solution 2: Use explicit profile
multica --profile <profile-name> <command>

# Solution 3: Set default profile
export MULTICA_PROFILE=<profile-name>

Pull Request Integration Issues

Problem: PR not linking to Multica issue

# Solution 1: Include routable issue key in PR title or body
# Format: MUL-123 or MUL-123: description

# Solution 2: Use close intent in PR body
Closes MUL-123
# or
Fixes MUL-123
# or
Resolves MUL-123

# Solution 3: Check if issue key is correct
multica issue get MUL-123 --output json

Problem: Can't see linked PRs in Multica

# Solution: Read from Multica, not GitHub
multica issue pull-requests <issue-id> --output json

# Don't guess from GitHub search or metadata

General Debugging Tips

  1. Always use --output json for programmatic parsing and detailed error messages

  2. Read before write - always check current state before making changes

  3. Check prerequisites - verify auth, workspace, and permissions first

  4. Use --help for any command you're unsure about

  5. Check version - ensure you're using the latest CLI version

    multica version
multica update  # if update available

  6. Enable verbose output for more details

    # Some commands support --verbose or --debug
multica issue get <id> --output json --verbose

  7. Check CLI logs if commands fail unexpectedly

    # Check daemon logs if running
multica daemon logs