Skill registry

The skill registry is Orcho’s capability routing layer.

Plugins tell Orcho what a project is. Prompt parts tell Orcho how a phase should speak. Skills tell Orcho which specialized instruction package can help with a specific subtask.

project facts
  -> skill registry
  -> compact skill roster
  -> architect selects a skill for a subtask
  -> executing worker receives the full skill package
  -> binding is recorded for evidence

In a live run, the registry should be visible near the top:

Plugin  orcho-core
Skills  14: orcho-core-cli-ux, orcho-core-cross-project,
            orcho-core-evidence-observability,
            orcho-core-quality-gates,
            orcho-core-skills-registry,
            orcho-core-verification-matrix,
            orcho-prompt-engine

That line is not a decoration. It tells the operator which domain procedures were available for planning and subtask routing before any worker starts editing.

What a skill is

A skill is a portable instruction package, normally a SKILL.md file with a name, description, body, and optional resources such as references, scripts, or assets.

The important boundary:

Skills provide instructional content. Orcho still owns runtime selection, model selection, profile policy, phase order, parser contracts, and gates.

That keeps skills useful without letting a copied project folder silently take over how Orcho runs.

Discovery sources

For one run, Orcho builds a merged registry from layered sources:

Priority	Source	Purpose
1	`project/.agents/skills/`	Project-owned canonical skills.
2	`project/.claude/skills/`	Claude-compatible project skills.
3	`project/.forge/skills/`	Forge-compatible project skills.
4	`workspace-orchestrator/.agents/skills/`	Shared skills for a project group.
5	`~/.agents/skills/`	User-level shared skills.
6	`orcho.skills` entry points	Installed package-provided skills.

Higher-priority sources shadow lower-priority sources with the same name. That is the customer-overlay contract: project-local knowledge can override shared defaults when the operator explicitly trusts it.

Trust policy

The registry is intentionally not “load every skill you can find.”

Default trust is conservative:

Source	Default
installed packages	loaded
user skills	loaded
workspace skills	loaded
project `.agents/skills/`	skipped until trusted
project `.claude/skills/`	skipped until trusted
project `.forge/skills/`	skipped until trusted

Project and compatibility skills are off by default because cloned repositories can contain hostile instructions. A repository can opt into local skills when the operator or project policy trusts that source.

Roster versus full skill body

Orcho does not paste every skill body into the planning prompt.

The planning surface receives a compact roster:

Available skills:
- `api-contract-review`: Review producer/consumer API compatibility.
- `pytest-fixtures`: Work safely with pytest fixture trees.
- `mcp-protocol`: Inspect MCP tool/resource/schema changes.

The architect can then route a subtask by naming the skill. Only the executing subtask receives the full SKILL.md body and resource list.

This keeps planning bounded while preserving deep instructions where they are actually needed.

Evidence

When a skill is used, Orcho records a binding:

skill_name: api-contract-review
activation: architect_selected
source: workspace
checksum: <skill-package-checksum>
phase: implement
subtask_id: T2-contract-check

That binding lets the operator answer:

which skill was used;
where it came from;
whether it was selected explicitly, by the architect, or by user request;
which phase or subtask used it;
which checksum was active at the time of the run.

If an agent loads a skill resource during execution, Orcho can also record a resource binding for the loaded file. The registry supports progressive disclosure: discover the package first, read resource bodies only when the worker actually needs them.

Where skills fit

Read the layers separately:

Layer	Owns
`plugin.py`	Project identity, architecture, paths, gates, review hints.
skill registry	Available domain capabilities and their provenance.
prompt engine	Role/task/format composition and protected contracts.
profile policy	Workflow depth, phase order, retries, and gates.
runtime adapter	How a worker CLI is invoked.

Skills are useful when the work needs a repeatable specialist procedure:

reviewing API compatibility;
touching generated golden files;
editing a framework with project-specific conventions;
auditing MCP schema changes;
working with a migration system;
applying a security or performance checklist to a subtask.

They are the wrong place for:

selecting a model or runtime;
changing phase order;
overriding parser schemas;
hiding task requirements that should be written in the task file;
storing secrets or private credentials.

Example

project/
└── .agents/
    └── skills/
        └── api-contract-review/
            ├── SKILL.md
            └── references/
                └── compatibility-checklist.md

The SKILL.md description should be specific enough that the architect can route subtasks without reading the whole body:

---
name: api-contract-review
description: Review producer/consumer API payload compatibility, contract tests, and backwards-compatibility risks.
---

The body can then contain the actual review procedure, examples, and resource usage. The architect sees the description; the executing worker gets the full skill when the subtask binds it.