---
title: Required Capabilities
description: Required skill and MCP discovery, installation, and setup issue guidance.
relatedCommands:
  - alpaca capability --help
  - alpaca skill --help
  - alpaca mcp --help
relatedDocs:
  - install
  - workflow-templates
  - workflow-template-authoring
  - hierarchical-workflows
  - setup
  - maintenance
---

# AlpacaLoop Required Capabilities

Use this guide when workflow templates declare or need `requires.skills` or `requires.mcp`, or when a run needs a reusable skill/MCP capability setup issue. Before running capability commands, inspect the relevant leaf command with `-h`; CLI help is the source of truth for current options.

## Key Commands

```bash
alpaca catalog topics list -h
alpaca capability list -h
alpaca capability search -h
alpaca skill list -h
alpaca skill search -h
alpaca skill catalog -h
alpaca skill create -h
alpaca mcp list -h
alpaca mcp search -h
alpaca mcp verify -h
alpaca mcp catalog -h
alpaca mcp create -h
```

## Required Skills and MCP

- Use `alpaca capability list -h`, then `alpaca capability list`, to inspect installed skill and MCP capabilities in one JSON view. Use `--include-excluded` only when debugging candidates that are visible but must not be used in workflow requirements.
- Use `alpaca capability search -h`, then `alpaca capability search "<capability>"`, for cross-type discovery before deciding whether the best fit is a skill, MCP server, or no declared requirement.
- Use `alpaca skill list -h`, then `alpaca skill list`, to inspect the final JSON inventory of skills available to configured workers.
- Use `alpaca catalog topics list` to inspect the shared topic vocabulary used by skill and MCP catalog entries.
- Use `alpaca skill catalog list -h`, then `alpaca skill catalog list`, to inspect repo-visible install candidates. Ejected system catalog entries are shown by default; use `alpaca skill catalog list --include-system` to include packaged system entries when the system catalog has not been ejected.
- Use `alpaca skill catalog add -h`, `alpaca skill catalog import-github -h`, and `alpaca skill catalog remove -h` before changing repo-visible skill catalog entries. Use `alpaca eject catalog` only when the packaged system catalog needs repo-local customization.
- Capability source policy: first decide whether the workflow's deliverable quality bar or observable evaluation evidence needs specialized support, then compare skill and MCP candidates by purpose fit, target narrowness, source trust, and quality signals. When a skill and MCP satisfy the same need equally well, prefer the usable skill. Use MCP when it is the better fit or the workflow truly needs configured live tool, resource, server, API, or MCP calls.
- Automated workflow plan review can also inspect capability-sensitive steps with bounded read-only capability search. When candidates are found, the accepted plan should carry exact selected, deferred, rejected, or no-specialized-capability decisions in visible plan fields using skill refs, usable installed MCP refs, MCP catalog ids, or search result ids. Catalog and search ids remain planning evidence, not `requires.skills` or `requires.mcp` values, until list or verify evidence proves a usable ref.
- For improvement or optimization workflows, require a skill or MCP only when the evaluation contract needs specialized guidance, live data, APIs, or tools to inspect baselines, metrics, source-of-truth evidence, measurement windows, target thresholds, or guardrails.
- Workflow template create/update prompt mode should run `alpaca capability list/search` as the first discovery view. Catalog ids and sources are discovery/install context, not valid `requires.skills` or `requires.mcp` values until the capability is installed or enabled and visible in the type-specific final inventory.
- Provider plugins are install mechanisms for enabling skills or MCP servers. AlpacaLoop does not have an `alpaca plugin` command, plugin catalog, plugin DB, or `requires.plugin`; after provider plugin install, re-run `alpaca skill list` and/or `alpaca mcp verify` and use only verified skill/MCP refs.
- `alpaca skill install` downloads or places a skill package for one worker. It does not automatically install npm packages, CLI tools, companion skills, OAuth credentials, browser login, or other runtime setup. Skill-resolution work should inspect these dependencies and, after explicit human confirmation of the exact install command, install needed safe non-auth dependencies rather than silently skipping them.
- Use `alpaca skill create --prompt <gap request>` only to create or preview a skill-resolution issue for a reusable skill support gap. The prompt is worker-drafted into a short title and capability summary before the final issue body is built.
- Workflow templates may declare `requires.skills` in frontmatter or via repeated `alpaca workflow create --required-skill <ref>`. Use the inventory item's `ref` value only when `usableForRequiredSkills: true`.
- Use `alpaca mcp list` and `alpaca mcp verify --ref <ref>` before declaring `requires.mcp`. Use `alpaca mcp catalog list`, `alpaca mcp search <query>`, and `alpaca mcp install --id <catalog-id> --for <worker>` for catalog-backed MCP setup after MCP is chosen as the best fit. Catalog entries are setup context, not `requires.mcp` availability proof; built-in workers need inventory proof, while Pi custom workers can expose project `.mcp.json` or `.pi/mcp.json` servers as usable server refs. Tool-level refs require inventory-reported tool names. MCP-resolution work should inspect the installed server command and setup metadata for required runtime dependencies, then ask for human confirmation before running needed safe non-auth dependency install commands.
- Use `alpaca mcp create --prompt <gap request>` only to create or preview an MCP-resolution issue for a reusable MCP server support gap. The prompt is worker-drafted into a short title and capability summary before the final issue body is built. OAuth, tokens, browser login, and admin approval are human handoff steps.
- Workflow templates may declare `requires.mcp` in frontmatter or via repeated `alpaca workflow create --required-mcp <ref>`. Valid refs are server names such as `github`, server/tool refs such as `github/list_issues`, or worker-qualified refs such as `codex:github` and `lmstudio-coder:github/list_issues`.
- Bare skill refs such as `browser-qa` represent shared or repo-local capabilities and leave only workers where that ref is usable as runtime candidates. Worker-qualified refs such as `codex:openai-docs`, `claude:browser-qa`, or `lmstudio-coder:repo-audit` constrain execution to workers that can use that worker's skill.
- If required skills are missing, or provider-qualified refs leave no runnable worker, AlpacaLoop follows `approvals.requirementsSetup.skills`: `auto` creates or reuses a required-skill setup child issue and blocks the parent with a dependency, while `confirm` hands off to a human instead of launching the worker.
- If required MCP refs are missing, AlpacaLoop follows `approvals.requirementsSetup.mcp`: `auto` creates or reuses a required-MCP setup child issue and blocks the parent with a dependency, while `confirm` hands off to a human instead of launching the worker.
- Setup issue reuse only considers open matching child issues. Closed setup children are history, and duplicate open setup children converge to one active blocker.
- Setup child issues use the parent issue's effective base branch. Ordinary unplanned child issues branch from the parent issue branch; reusable skill/MCP resolution children use the effective base branch because they update shared capability configuration rather than the parent branch.
- If token creation, OAuth, browser login, admin approval, secrets, or policy approval is needed, leave a Needs Human handoff with exact remaining steps and never write secret values into catalog or issue text.
- If planning or execution discovers a new reusable capability gap that is not already declared, create a skill-resolution or MCP-resolution child issue only when the gap blocks safe completion and is repo/tool/domain specific or likely to recur. Inspect cross-type options with `alpaca capability list/search` first; use `alpaca mcp create --prompt <gap request>` only when MCP is the better fit, including cases where live server/tool/resource/API access is the core missing capability. For one-off work, finish the current step or record a follow-up instead.

## Catalog Assets

Packaged catalog assets are curated starting points for discovering installable capabilities. They are not proof that a worker can already use a capability.

| File | What it contains | Main commands |
| --- | --- | --- |
| `package-assets/system/catalog/skill.json` | AlpacaLoop-curated skill install candidates and source locations. | `alpaca skill catalog list`, `alpaca skill search`, `alpaca skill install`. |
| `package-assets/system/catalog/mcp.json` | AlpacaLoop-curated MCP install candidates, discovery leads, server specs, and setup notes. | `alpaca mcp catalog list`, `alpaca mcp search`, `alpaca mcp install`, `alpaca mcp verify`. |
| `package-assets/system/catalog/metadata.json` | Shared topic descriptions and requirement exclusions for catalog search and workflow requires. | `alpaca catalog topics list`, `alpaca capability search`, `alpaca skill search`, `alpaca mcp search`. |

Use `alpaca eject catalog` only when the packaged catalog needs a repository-specific override. Ejected files live under `.alpaca/catalog/__system/` and replace packaged system catalog files for that repository. User-added catalog entries belong in `.alpaca/catalog/skill.json` or `.alpaca/catalog/mcp.json`; do not edit packaged files directly.

## Missing Requirement Setup

Treat unavailable declared requirements as pre-worker setup work, not ordinary `child_issue` plan steps.

For missing skills:

1. Inspect cross-type candidates with `alpaca capability list` and `alpaca capability search <query>`.
2. Decide whether the skill path remains the best fit; if MCP or no declared requirement is better, update the workflow/template path instead of forcing skill setup.
3. Inspect final usable skill refs with `alpaca skill list`.
4. Inspect repo-visible install candidates with `alpaca skill catalog list`.
5. Search skill-specific installed, catalog-backed, and marketplace candidates.
6. Install or enable a fitting installed, catalog-backed, or marketplace skill when available.
7. Ask a human before marketplace, direct GitHub/source URI, private, or ambiguous non-catalog installs.
8. Inspect skill docs for dependencies and auth, ask for human confirmation of exact dependency install commands, and install confirmed safe non-auth dependencies when needed.
9. Hand off for OAuth or human-only login with exact remaining steps.
10. Verify with help, version, or smoke commands when possible.
11. Create a repo-local skill only if no installed, catalog-backed, or marketplace candidate safely covers the capability.
12. Update workflow `requires.skills` only with final usable refs from `alpaca skill list` that are not excluded from workflow requires, then run `alpaca workflow lint --path <template>`.

For missing MCP refs:

1. Inspect cross-type candidates with `alpaca capability list` and `alpaca capability search <query>`.
2. Decide whether the MCP path remains the best fit; if a skill or no declared requirement is better, update the workflow/template path instead of forcing MCP setup.
3. Inspect `alpaca mcp list`.
4. Inspect MCP-specific candidates with `alpaca mcp catalog list --include-system` and `alpaca mcp search <query>`, treating discovery-only catalog entries as research leads.
5. Install only fitting catalog-backed entries that include a server spec and are safe for non-interactive setup.
6. Verify with `alpaca mcp verify --ref <ref>`.
7. Update workflow `requires.mcp` only with refs that `alpaca mcp verify` reports usable and are not excluded from workflow requires, then run `alpaca workflow lint --path <template>`.

Treat an MCP install result `ref` as a candidate until `mcp verify` confirms it is usable.

## Related Docs

- `alpaca docs show workflow-templates`
- `alpaca docs show workflow-template-authoring`
- `alpaca docs show hierarchical-workflows`
- `alpaca docs show install`
- `alpaca docs show setup`
- `alpaca docs show maintenance`
