/install-skill — importa skills do ateliê para o workspace atual

As skills nascem no ateliê (~/.claude/skills) e ficam lá inertes. Esta skill é a ponte: copia a subpasta de uma skill do ateliê para onde ela vai rodar — o .claude/skills/ do projeto atual (default) ou ~/.claude/skills/ (global). O ateliê é a origem read-only: você só escreve no alvo, nunca altera a origem.

Conceitos

• Origem (ateliê): ~/.claude/skills por default — sobreponha com a env SKILLS_WORKSHOP se ela existir. Cada subpasta com um SKILL.md é uma skill instalável. Somente leitura.
• Alvo projeto (default): <raiz-do-projeto>/.claude/skills/<nome>/. A raiz é o ancestral mais próximo do diretório atual que contém um .claude/; se não houver nenhum, é o próprio diretório atual (confirmar antes de criar .claude/ ali).
• Alvo global: ~/.claude/skills/<nome>/. Fica disponível em qualquer workspace. Uma skill com scope: global no frontmatter pede esse alvo por default.

Motor determinístico

As partes mecânicas (descobrir skills, resolver o alvo, comparar, copiar) ficam no script bundled desta skill — no global ativo: $HOME\.claude\skills\install-skill\scripts\manage-skills.ps1. Ele devolve JSON em stdout; você lê o JSON e cuida só das decisões/interação. Invoque sempre via:

pwsh -NoProfile -File "$HOME\.claude\skills\install-skill\scripts\manage-skills.ps1" -Command <cmd> [args]

Passos

1. Descobrir o que há para instalar

-Command list → { workshop, count, skills:[{name, scope, description, path}] } (já pula .skill-research/ e pastas ocultas; origem = ~/.claude/skills ou $env:SKILLS_WORKSHOP). Se skills vier vazio, avise e pare.

2. Selecionar quais skills

• Nome(s) em $ARGUMENTS → use direto. all → todas (exclua a própria install-skill, salvo --global explícito, para não instalar a ferramenta de instalação dentro de um projeto sem querer).
• --list ou nenhum nome → mostre a tabela nome · scope · descrição do passo 1. Com ≤4 skills, use AskUserQuestion (multiSelect); com mais, peça os nomes ao usuário.

3. Resolver o alvo

-Command resolve-target [-StartDir <cwd>] [-Global] [-Here] → { targetSkillsDir, projectRoot, claudeExisted, global }. Regras:

• default: sobe do cwd até o .claude/ ancestral (trata repos com .claude/ aninhado). Se claudeExisted=false, o alvo ainda não existe e será criado — confirme antes.
• --global (ou skill scope: global) → ~/.claude/skills.
• --here → força o cwd como raiz.

Sempre mostre o targetSkillsDir resolvido antes de copiar.

4. Instalar (conflito já tratado pelo motor)

-Command install -Name <skill> -TargetDir <targetSkillsDir> [-Force] copia a subpasta inteira (SKILL.md + scripts//references//assets/) e devolve status:

• installed — novo, copiado.
• skipped-identical — já está lá idêntico; nada a fazer.
• conflict — existe e difere: pergunte ao usuário (sobrescrever / pular) e só re-execute com -Force se ele topar.
• updated — sobrescrito (só acontece com -Force).
• no-such-skill — nome não existe no ateliê.

Para checar antes de decidir, sem copiar: -Command status -Name <skill> -TargetDir <dir> → absent | identical | differs.

5. Reportar

• Tabela final: skill · scope · path-alvo · status.
• Lembre que o Claude Code carrega .claude/skills/ no início da sessão — pode ser preciso reabrir a sessão para a skill nova aparecer. Diga se foi instalação de projeto ou global.

Sincronizar a própria install-skill

A install-skill é global e tem cópia de desenvolvimento no ateliê. Depois de editá-la lá, ressincronize a cópia ativa com:

/install-skill install-skill --global

Exemplos de tradução

Guardrails

• Origem é read-only. Só escreva em <raiz>/.claude/skills/ (projeto) ou ~/.claude/skills/ (global).
• Confirme o path-alvo antes de copiar; confirme qualquer overwrite.
• Não instale uma skill que não exista no ateliê — liste o que há e peça para escolher.
• Silos ICM: instalar uma skill num projeto não autoriza mexer em mais nada dele. A única escrita é a cópia da subpasta da skill.