oro skills

Visão geral

Instala e atualiza skills gerenciadas no projeto a partir de dois catálogos: as skills bundled da recipe do manifest (embutidas no binário) e o catálogo público github:willsantos/skills_AI. O estado instalado fica em .orotools/skills.lock.yaml, versionável junto com o código.

O destino das skills é definido por ai.agent do orotools.yaml (.opencode/skills, .cursor/skills, .claude/skills, .codex/skills, .github/skills); manifests legados sem ai.agent usam opencode.

O catálogo bundled é resolvido do registry oficial embutido (dotnet, dotnet-next, fastify-next, rails). Projetos gerados a partir de uma recipe local não têm bundled catalog resolvível — apenas as skills gerenciadas do GitHub seguem funcionando.

Comandos

oro skills                    # wizard interativo: mostra instaladas e instala a seleção
oro skills update             # atualiza todas as skills gerenciadas (não interativo)
oro skills update --dry-run   # só mostra as decisões, sem modificar nada
oro skills update --force     # substitui também skills com alterações locais

Ambos aceitam --manifest <path> para apontar para um orotools.yaml fora do diretório atual (a base do projeto é o diretório do manifest).

Modo ad-hoc (sem orotools.yaml)

Os comandos também funcionam em projetos que não são projetos Oro — basta haver (ou vir a haver) uma pasta de skills:

• Catálogo: apenas github:willsantos/skills_AI (o catálogo bundled depende da recipe declarada no manifest). O lock continua sendo criado em .orotools/skills.lock.yaml, então oro skills update funciona depois.
• Destino: no wizard, --agent <id> instala em um único agent; com mais de uma pasta de skills detectada (.opencode/skills, .cursor/skills, .claude/skills, .codex/skills, .github/skills), a TUI lista os agents encontrados para marcar vários — as skills selecionadas instalam em todos. Uma única pasta detectada é usada diretamente; nenhuma pasta usa o default opencode. Sem terminal no stdin, múltiplas pastas seguem sendo erro acionável (use --agent).
• No oro skills update (não interativo), cada entrada do lock é atualizada no agent do próprio target — locks com múltiplos agents são processados normalmente; --agent é ignorado (nota informativa).
• Com orotools.yaml presente, --agent é rejeitado (o agent vem de ai.agent); --manifest explícito apontando para arquivo inexistente continua sendo erro.

cd qualquer-projeto        # sem orotools.yaml
oro skills                 # wizard: seleciona agents (se ambíguo) e skills
oro skills --agent codex   # destino único e explícito
oro skills update          # atualiza o que o lock registra, por agent

Wizard oro skills

$ oro skills
Skills já instaladas
  ✓ code-review                   1.0.0    recipe:dotnet

Selecione as skills para instalar
  ◉ aspnet 1.0.0 recipe:dotnet — ASP.NET Core conventions
  ◯ local-pr-review 1.0.0 github:willsantos/skills_AI — Review PRs locally

• Skills já instaladas aparecem na seção inicial e nunca são removidas — desmarcar no wizard não desinstala. Em locks com mais de um agent, a listagem mostra o diretório de destino de cada entrada.
• A seleção de skills é multi-select; seleção vazia (ou cancelar) termina sem modificar nada. Na seleção de agents (modo ad-hoc ambíguo), enter exige ao menos um agent marcado; esc cancela o wizard.
• Multi-agent: a mesma skill pode viver em vários agents; o lock registra uma entrada por destino. O wizard só oferece skills que ainda faltam em pelo menos um dos agents marcados, e a instalação repete o par (skill × agent) atomicamente — falha em um destino não aborta os demais.
• Instalação é create-only: um diretório de destino que já exista sem registro no lock é conflito — nada é adotado nem sobrescrito sem --force.
• Cada skill é instalada atomicamente (staging + swap); falha em uma não impede as demais.
• Se o catálogo GitHub estiver inacessível, o wizard avisa e segue com as skills bundled. Sem um terminal no stdin, o comando falha antes de qualquer mutação (use oro skills update).

Update oro skills update

Cobre tudo que está no lock (bundled + github:willsantos/skills_AI); skills.external fica fora do escopo. Relatório determinístico e exit code agregado (1 se houver bloqueio ou falha):

+ code-review                   1.0.0 → 1.1.0
= local-pr-review               1.0.0 (atual)
! azure-mermaid-compatible      1.0.0 — alterações locais detectadas; use --force

• Versão maior publicada → atualiza. Downgrade publicado → ignora com aviso. Mudança só de build metadata não força atualização.
• Alterações locais (qualquer arquivo diferente do digest do lock) bloqueiam a skill individualmente; --force substitui e avisa que as mudanças serão perdidas.
• Skill bundled com conteúdo alterado sem bump de metadata.version é erro de empacotamento.
• Se ai.agent mudar para um target diferente do registrado, a skill é bloqueada (mover entre agents não é suportado). Sem manifest, cada entrada é atualizada no agent do próprio target — locks mistos funcionam.
• Referência que sumiu do catálogo não remove o destino; o item falha no relatório.
• --dry-run valida os catálogos e mostra as decisões sem tocar em nada.

orotools.yaml schema v2 e lock

A primeira skill gerenciada do catálogo GitHub promove o manifest para o schema v2, registrando a escolha (não a versão — a versão instalada vive no lock):

version: 2
skills:
  bundled:
    - base/code-review
  managed:
    - source: github:willsantos/skills_AI
      name: local-pr-review

O lock registra origem, versão, revisão (commit SHA do GitHub), destino e o digest do conteúdo — sem timestamps nem caminhos absolutos. A unicidade é pelo par (id, target): a mesma skill instalada em agents distintos são entradas distintas do mesmo lock. Skills bundled legadas (instaladas antes do lock) são adotadas automaticamente quando o conteúdo do destino coincide com a origem corrente; divergentes ficam marcadas como não gerenciadas até um oro skills update --force.

Rede, limites e segurança

• O snapshot do catálogo GitHub é baixado uma única vez por execução e fixado no commit SHA resolvido; nada é misturado entre revisões.
• GITHUB_TOKEN é opcional (ajuda no rate limit); nunca é gravado no manifest nem no lock, nem aparece nos logs.
• Limites por execução: 200 entradas de catálogo, 500 arquivos e 20 MiB por skill, 50 MiB por snapshot. Symlinks e arquivos especiais são rejeitados.
• Nenhum código das skills é executado — apenas transferência validada de arquivos, preservando o bit executável.