zhangliang0115/ai-plugin

Criando uma habilidade SKILL.md entre agentes

Uma habilidade é uma pasta com um arquivo SKILL.md dentro. O arquivo começa com um bloco YAML de frontmatter (nome + descrição) seguido por instruções em Markdown que o agente carrega sob demanda. Como Claude Code, DeepSeek Harness (dsh), Codex CLI, Gemini CLI, Copilot e Cursor todos leem este mesmo formato, uma habilidade bem escrita atende a todos os agentes.

Anatomia

minha-habilidade/
├── SKILL.md            # obrigatório: frontmatter + instruções
├── references/         # opcional: documentos longos que o modelo lê sob demanda
└── scripts/            # opcional: scripts auxiliares que a habilidade pode executar

---
name: minha-habilidade
description: >-
  Uma ou duas frases: o que faz E quando usar. É o gatilho que o agente
  compara com a solicitação do usuário — escreva como uma regra de roteamento.
---

# Minha habilidade

Instruções passo a passo. Suponha um engenheiro competente; seja concreto, não vago.

Regras que decidem se uma habilidade funciona

1. name deve estar em kebab-case — letras minúsculas, dígitos, hífens; máximo 64 caracteres. Agentes rejeitam ou distorcem outros nomes. aipx normaliza para você, mas envie correto.
2. description é o gatilho, não documentação. Ruim: "Utilitários para trabalhar com coisas." Bom: "Resumir vídeos do YouTube/Bilibili e podcasts a partir de uma URL. Use quando o usuário colar um link de vídeo ou áudio."
3. Mantenha SKILL.md abaixo de ~500 linhas. Coloque profundidade em references/*.md e link para eles ("veja references/schema.md"). Os agentes carregam o corpo apenas quando a habilidade é acionada; corpos grandes desperdiçam contexto e diluem o comportamento.
4. Sem habilidades aninhadas. A descoberta varre apenas os filhos diretos de uma raiz de habilidades — skills/a/SKILL.md é encontrado, skills/a/b/SKILL.md não.
5. Links relativos devem permanecer relativos. Se SKILL.md referencia scripts/x.py, a pasta inteira viaja junta — nunca link para fora do diretório da habilidade.

Onde as habilidades vivem (raízes do usuário)

Raiz	Lido por
~/.agents/skills/<nome>/SKILL.md	DeepSeek Harness (dsh), Codex CLI
~/.claude/skills/<nome>/SKILL.md	Claude Code
~/.gemini/skills/<nome>/SKILL.md	Gemini CLI
~/.copilot/skills/<nome>/SKILL.md	GitHub Copilot CLI

Existem equivalentes no escopo do projeto também (ex.: .claude/skills/, .agents/skills/ no repositório). Não copie manualmente — use aipx sync para vincular uma cópia em cada raiz do agente.

Teste antes de publicar

# ele é analisado e descoberto?
aipx install ./minha-habilidade --dry-run
aipx install ./minha-habilidade
aipx list

Em seguida, abra seu agente e confirme se a habilidade aparece (Claude Code: aparece na lista de habilidades; dsh: paleta de comandos / → grupo Habilidades).

Lista de verificação para publicação

• O repositório contém a pasta da habilidade em um caminho estável, ex.: skills/minha-habilidade/
• description declara condições de gatilho, não apenas funcionalidades
• Funciona a partir de uma instalação limpa (aipx install owner/repo#path:/skills/minha-habilidade)
• Adicione tópicos do GitHub para que a descoberta funcione: agent-skills, claude-code, dsh-plugin (se também enviar um pacote dsh), deepseek (se relacionado a DS)
• Opcional: empacotamento de alvo duplo — veja as habilidades dsh-plugin-dev e claude-plugin-dev