---
name: alpaca
description: "Operate AlpacaLoop control-plane tasks with the `alpaca` CLI. Use when the request concerns the managed-work lifecycle or repository automation for AI work, including managed issues, workflow templates, event hooks, schedules/recurring runs, service/auth/worker health, publishing, labels/state repair, required skill/MCP/capability setup, or inspecting another repository through AlpacaLoop. Start with `alpaca -h` to choose the command path. Do not use for ordinary product code changes unless the outcome depends on AlpacaLoop workflow or control-plane behavior."
license: UNLICENSED
compatibility: Designed for project-local Claude Code or Codex skills. Requires `alpaca` in PATH and access to the tracked repository and configured ticket tracker. Best with `git` plus provider-specific tooling from the repository root.
metadata:
  alpaca-managed: "true"
  alpaca-role: "repository-control-plane"
  alpaca-distribution: "repository-local"
allowed-tools: Bash(alpaca:*) Bash(git:*) Bash(gh:*) Bash(glab:*)
---

# AlpacaLoop

## When to use this skill

Use this skill for AlpacaLoop control-plane work: repository setup, issue/task queue inspection, workflow template work, required skill/MCP setup, event hooks, service health, scheduled/recurring run state, and managed issue/task state. Do not use it for ordinary product code changes unless the request specifically involves AlpacaLoop workflow behavior.

Use provider-specific tooling for the configured ticket tracker. For GitHub, use GitHub MCP first; if it is unavailable, use an installed GitHub skill. Use `alpaca` from the target repository root when inspecting or running the AlpacaLoop control plane.

## References

Use `alpaca docs` as the entry point for AlpacaLoop reference material. Run `alpaca docs list --with-description` to choose a topic, `alpaca docs show <topic-id|docs-path>` to read one reference, `alpaca docs show <topic-id> --web` to open its GitHub page, and `alpaca docs search <query>` to search with context snippets. Use `alpaca docs search <query> --view headings` to inspect matching docs outlines before reading full references. A docs path is either `references/...md` or `skills/alpaca/references/...md`.

## Command discovery

For AlpacaLoop CLI requests, check the relevant `alpaca ... -h` help before running commands, searching source code, or deciding implementation work. If help identifies the command, option, constraints, and examples needed for the request, follow that help directly instead of inspecting implementation details. When the command family is unclear, narrow it in order: `alpaca -h`, then `alpaca <group> -h`, then `alpaca <group> <command> -h`.

`SKILL.md` is the quick map. Detailed option meanings, allowed values, conflicts, notes, and examples belong to CLI help. Prefer `-h` when exploring commands:

```bash
alpaca -h                         # Search top-level commands.
alpaca <group> -h                 # Search subcommands inside a command group.
alpaca <command> -h               # Inspect options for a top-level command.
alpaca <group> <command> -h       # Inspect options for a grouped command.
alpaca docs                       # List docs topics with descriptions.
alpaca docs list                  # List skills/alpaca/references/*.md paths.
alpaca docs show <topic-id>      # Read by topic ID from docs list metadata.
alpaca docs show <docs-path>     # Read by docs path from docs list output.
alpaca docs show <topic-id> --web # Open the docs GitHub page in a browser.
alpaca docs search <query>        # Search concept docs with context snippets.
alpaca docs search <query> --view headings # Search docs and show matching docs outlines.
alpaca help --all                 # Read the full generated CLI reference when needed.
```

Default command flow:

1. Run `alpaca -h` to find the command family.
2. If the target is grouped, run `alpaca <group> -h` to find the leaf command.
3. Before invoking a leaf command, run its `-h` page and check Usage, Options, Notes, and Examples.
4. For AlpacaLoop reference material, run `alpaca docs`, `alpaca docs show <topic-id|docs-path>`, or `alpaca docs search <query>`.
5. Execute the command with the exact options confirmed from help.

Do not infer detailed option behavior from this file. If an option is unfamiliar, destructive, public-facing, or mode-dependent, check the relevant `-h` output immediately before use.

## Common routes

These are starting points, not a full command inventory. Run `alpaca -h` when the task does not fit one route.

- Status and progress: `alpaca issue list -h`, `alpaca issue search -h`, `alpaca issue show -h`
- Issue creation, approval, start approval, pause/re-enable, follow-up, and queue updates: `alpaca issue create -h`, `alpaca issue approve -h`, `alpaca issue start -h`, `alpaca issue disable -h`, `alpaca issue enable -h`, `alpaca issue followup -h`, `alpaca issue broadcast -h`, `alpaca issue unlock -h`
- Local issue logs: `alpaca issue log -h`
- Workflow templates: `alpaca workflow -h`, `alpaca workflow create -h`, `alpaca workflow update -h`, `alpaca workflow delete -h`, `alpaca workflow lint -h`, `alpaca workflow list -h`
- Required capabilities: `alpaca capability -h`, `alpaca capability list -h`, `alpaca capability search -h`, `alpaca catalog topics list -h`, `alpaca skill -h`, `alpaca skill list -h`, `alpaca skill search -h`, `alpaca skill catalog -h`, `alpaca mcp -h`, `alpaca mcp list -h`, `alpaca mcp search -h`, `alpaca mcp catalog -h`, `alpaca mcp verify -h`
- Event hooks: `alpaca event-hook -h`
- Canonical workflow state repair: `alpaca state -h`
- Labels: `alpaca labels sync -h`
- Health and service state: `alpaca doctor -h`, `alpaca service -h`, `alpaca service status -h`, `alpaca service log show -h`
- Publish and worker execution: `alpaca publish -h`, `alpaca run -h`
- Setup and cleanup: `alpaca init -h`, `alpaca auth -h`, `alpaca detach -h`, `alpaca cleanup -h`

## Hard guards

- Do not run `alpaca run` while the background service is running.
- Use `alpaca issue create` only when the user explicitly asks to create, file, record, or publish an issue or ticket.
- When review is needed or approval is unclear, use `--save-draft`, show the draft, and after approval apply the same JSON with `--apply-draft <path|->`. Do not rerun prompt mode for an approved draft.
- Use `alpaca publish` when local repository changes must become visible to service automation. After workflow create/update/delete, use `alpaca publish --path .alpaca/workflows` when only workflow templates should be published.
- Treat secrets, OAuth, browser login, admin approval, and policy approval as human handoff steps. Never write secret values into catalog entries, issue text, or workflow templates.
- Use the references for AlpacaLoop-specific draft/apply flows, labels, workflow update format, workflow template references, and required skill/MCP setup behavior.
