---
description: "System workflow for resolving reusable skill support"
targets:
  - issue
  - unplanned
  - followup
autoSelect: false
updateMode: strict
requires:
  skills: []
---
# Skill Resolution

## Goal

Resolve a missing reusable capability by finding, installing, enabling, or authoring the smallest fitting skill, then return the parent issue to a runnable state.

## Rules

- Treat this issue as capability resolution, not as the parent issue implementation.
- Evaluate existing local, installed, catalog-backed, marketplace, and MCP alternatives with `alpaca capability list` and `alpaca capability search` before creating a new repository-local skill; install marketplace, direct GitHub/source URI, private, or ambiguous non-catalog sources only after human approval.
- Runtime dependencies for the selected skill, such as required CLI tools, npm packages, Python packages, companion skills, local services, or native apps, should normally be installed when they are needed and have a documented safe non-auth setup path, but only after explicit human confirmation of the exact install command or setup action.
- Create or update workflow `requires.skills` only after the correct usable `ref` is visible in `alpaca skill list` and is not excluded from workflow requires.
- Keep worker-specific differences explicit for Codex and Claude instead of assuming one skill layout fits both.

## Required Process

- Run `alpaca capability list` and `alpaca capability search "<capability>"` first to compare installed and installable skill/MCP candidates in one view.
- Run `alpaca skill list` and identify currently usable refs for the target worker set after the skill path remains the best fit.
- Run `alpaca skill catalog list` and evaluate repo-visible install sources only after the skill path remains the best fit.
- Run `alpaca skill search "<capability>"` and evaluate installed, catalog-backed, and marketplace candidates when the skill path remains the best fit.
- Reuse a fitting installed skill when available. Otherwise install or enable a fitting catalog-backed or marketplace candidate, then confirm it appears in `alpaca skill list`. Treat `alpaca skill install` as downloading or placing the skill package; it does not automatically install npm packages, CLI tools, companion skills, OAuth credentials, browser login, or other runtime setup.
- Prefer the smallest source that contains the needed `SKILL.md` and supporting files; do not download an entire multi-skill repository when a single skill directory is sufficient.
- Ask a human before installing any marketplace, direct GitHub/source URI, private, or ambiguous non-catalog source.
- Inspect the installed skill's `SKILL.md`, README, `package.json`, `skill.json`, and nearby docs for required CLI tools, npm packages, companion skills, setup commands, and authentication requirements.
- For missing non-auth dependencies, prepare the smallest documented install command or setup action, ask a human to confirm it, then run it when confirmed. Do not silently skip dependency installation when the dependency is required to run or verify the skill.
- If OAuth, credentials, marketplace access, browser-based login, admin approval, OS permission grants, or GUI-only setup is required, complete any confirmed non-auth setup, write the exact human authentication or permission steps, and hand off instead of pretending the skill is fully verified.
- Verify the installed skill by running the documented help, version, or smallest safe smoke command when possible. If credentials block verification, report the completed setup and the remaining human step.
- Create a repo-local skill only when no installed, catalog-backed, or marketplace candidate safely covers the capability.
- When authoring a skill, include `SKILL.md` with clear frontmatter and only add scripts, references, assets, or worker-specific files when they are required.
- Update workflow `requires.skills` only when the workflow should depend on the resolved skill for future runs.
- Run `alpaca workflow lint` and fix any workflow or required skill failures.

## Handoff To Human When

- The needed capability requires credentials, private marketplace access, or approval to install third-party code.
- The skill requires OAuth, browser login, or another human-only authentication step after non-interactive setup is prepared.
- Multiple installable skill candidates fit and choosing one changes security, licensing, or maintenance ownership.
- The requested capability is too broad to validate as a reusable skill in this issue.

## Success Criteria

- The capability is satisfied for the target worker set by an installed, enabled, or newly created skill.
- Required non-auth dependency setup is completed after explicit human confirmation; if dependency installation, authentication, or permissions remain blocked, exact steps are provided and the issue waits for that human action instead of closing as fully verified.
- A documented help, version, or smoke command has been run successfully when the skill can be verified without human-only authentication; otherwise verification is explicitly deferred until after auth.
- Any workflow `requires.skills` updates use refs that appear usable in `alpaca skill list` and are not excluded from workflow requires.
- `alpaca workflow lint` passes.
- The issue result names what was installed, enabled, created, or intentionally reused.
