Tutorial: Criando seu Repo de Skills

1. Introdução

Um skill repo é um repositório Git contendo skills, agents e/ou hooks gerenciáveis pelo Skill Manager for Copilot.

Qualquer repositório Git — público ou privado — pode ser um skill repo. Basta seguir a estrutura de pastas esperada e, opcionalmente, adicionar um arquivo de configuração. O Skill Manager cuida do resto: sincronização, versionamento e distribuição.

O que você vai aprender neste tutorial:

• Como organizar a estrutura de pastas do seu repo
• Como configurar o .skillmanager.json
• Como criar skills, agents e hooks
• Como adicionar seu repo ao Skill Manager

2. Estrutura mínima

O mínimo necessário para um skill repo funcional é uma pasta de skills com pelo menos uma skill contendo um SKILL.md:

meu-repo/
├── .skillmanager.json    # (opcional) configuração do repo
└── skills/
    └── minha-skill/
        └── SKILL.md      # definição da skill

3. .skillmanager.json — Configuração do repositório

O .skillmanager.json fica na raiz do repositório e permite personalizar caminhos e comportamentos. Aqui está a configuração completa com todos os campos disponíveis:

{
  "skills": {
    "path": "skills",
    "protectedBranch": "main"
  },
  "agents": {
    "path": "agents"
  },
  "hooks": {
    "path": "hooks"
  },
  "benchmarks": {
    "path": "skill-benchmarks"
  },
  "neuralLink": {
    "isRuntime": false,
    "path": "",
    "configTemplate": ""
  },
  "feedback": {
    "defaultThreshold": 5,
    "branchPattern": "feedback/{author}/{skill}/v{version}",
    "reviewStorageLocal": ".vscode/skill-reviews"
  }
}

Campos explicados

skills

Exemplo: Se suas skills estão em src/copilot-skills/:

{
  "skills": {
    "path": "src/copilot-skills",
    "protectedBranch": "main"
  }
}

agents

hooks

benchmarks

neuralLink

Configuração do Neural Link runtime. Relevante apenas para repos que incluem o runtime do Neural Link (como o Skill Kit oficial).

feedback

Configuração do sistema de feedback e push de melhorias.

Quando o .skillmanager.json é necessário?

Se o arquivo não existir, todos os defaults acima são aplicados automaticamente. Você só precisa criá-lo se quiser:

• Mudar a pasta de skills, agents ou hooks
• Configurar um branch protegido diferente de main
• Ajustar o padrão de branches de feedback
• Indicar que o repo contém um runtime do Neural Link

4. Criando uma Skill

Estrutura de uma skill

Cada skill é uma subpasta dentro da pasta de skills (skills/ por padrão):

skills/
└── minha-skill/
    ├── SKILL.md           # (obrigatório) definição da skill
    ├── FEEDBACK.md        # (opcional) template de feedback
    └── references/        # (opcional) arquivos de referência
        └── exemplo.md

Exemplo de SKILL.md

---
version: 1.0.0
---

# Gerador de Testes Unitários

**WORKFLOW SKILL** — Gera testes unitários automaticamente para funções e classes.

## Quando usar

- Ao criar novas funções ou classes que precisam de cobertura de testes
- Ao refatorar código existente que não tem testes

## Instruções

1. Analise a função ou classe alvo
2. Identifique os cenários de teste: caminho feliz, edge cases, erros
3. Gere testes usando o framework de teste do projeto (Jest, Mocha, pytest, etc.)
4. Inclua assertions claras e descritivas
5. Nomeie os testes seguindo o padrão: "should [comportamento] when [condição]"

## Exemplo

Para uma função `soma(a, b)`:

```javascript
describe('soma', () => {
  it('should return the sum of two positive numbers', () => {
    expect(soma(2, 3)).toBe(5);
  });

  it('should handle negative numbers', () => {
    expect(soma(-1, 1)).toBe(0);
  });
});
```

Frontmatter YAML

O bloco entre --- no início do arquivo é o frontmatter YAML. Campos suportados:

Exemplo de FEEDBACK.md

# Feedback — Gerador de Testes Unitários

## O que funcionou bem?

<!-- Descreva o que a skill fez corretamente -->

## O que pode melhorar?

<!-- Sugestões de melhoria -->

## Contexto

- **Linguagem:** (ex: TypeScript, Python)
- **Framework de testes:** (ex: Jest, pytest)
- **Tipo de código:** (ex: função pura, classe com dependências)

5. Criando um Agent

Agents são arquivos .agent.md que definem assistentes personalizados com comportamentos específicos. Ficam na pasta agents/ por padrão:

agents/
└── meu-agent.agent.md

Exemplo de .agent.md

---
description: "Agent especialista em code review com foco em segurança"
---

# Security Reviewer

Você é um especialista em revisão de código com foco em segurança.

## Responsabilidades

- Analisar código em busca de vulnerabilidades comuns (OWASP Top 10)
- Verificar tratamento adequado de inputs do usuário
- Identificar credenciais ou segredos expostos no código
- Sugerir correções com exemplos práticos

## Regras

- Nunca aprove código com SQL injection, XSS ou CSRF
- Sempre sugira o uso de prepared statements para queries SQL
- Valide que toda entrada do usuário é sanitizada antes do uso

Frontmatter do Agent

6. Criando Hooks

Hooks são scripts executados automaticamente em eventos específicos do agente (como antes de usar uma ferramenta ou ao finalizar). Ficam na pasta hooks/ por padrão:

hooks/
└── scripts/
    ├── pre-commit-guard.sh     # Unix
    ├── pre-commit-guard.ps1    # Windows
    ├── stop-checklist.sh
    └── stop-checklist.ps1

Hooks suportam scripts .sh (Unix) e .ps1 (Windows). O Skill Manager seleciona automaticamente o script correto para a plataforma.

Eventos suportados:

7. Adicionando ao Skill Manager

Existem 3 formas de adicionar seu repositório ao Skill Manager:

Via Command Palette

1. Abra o VS Code
2. Ctrl+Shift+P (ou Cmd+Shift+P no macOS)
3. Digite Skills: Add Repository
4. Cole a URL do seu repositório Git (ex: https://github.com/seu-usuario/meu-skill-repo)

Via Sidebar

1. Abra a sidebar do Skill Manager (ícone na Activity Bar)
2. Clique no ícone "+" (Add Repository)
3. Cole a URL do repositório

Compartilhando com outros

Se o seu repositório é público, qualquer pessoa pode adicioná-lo ao Skill Manager dela usando os mesmos passos acima. Basta compartilhar a URL do repo!

8. Sincronização

Pull automático

O Skill Manager sincroniza automaticamente com os repositórios configurados. O intervalo padrão é de 3600 segundos (1 hora) e pode ser configurado em:

Settings → skillManager.syncInterval (valor em segundos; 0 desabilita o sync automático)

Pull manual

Ctrl+Shift+P → Skills: Pull All

Isso sincroniza todas as skills, agents e hooks de todos os repositórios configurados.

Push de melhorias

Quando você melhora uma skill localmente e quer contribuir de volta:

1. Clique com botão direito na skill na sidebar → Push Improvement
2. Ou use Ctrl+Shift+P → Skills: Push Improvement

O Skill Manager cria automaticamente uma branch seguindo o padrão configurado (ex: feedback/{author}/{skill}/v{version}), commita as mudanças e fornece o link para abrir o Pull Request.

9. Publicando seu repo como Template

Para facilitar que outros usem seu repositório como referência:

Boas práticas

• Adicione um README.md na raiz com instruções claras sobre o conteúdo do repo e como usá-lo
• Use .skillmanager.json para documentar explicitamente a estrutura, mesmo que use os defaults — isso serve como documentação
• Adicione FEEDBACK.md em cada skill para facilitar contribuições da comunidade
• Organize por domínio — agrupe skills relacionadas em subpastas dentro de skills/:

skills/
├── testing/
│   ├── unit-test-generator/
│   │   └── SKILL.md
│   └── test-reviewer/
│       └── SKILL.md
├── security/
│   ├── vulnerability-scanner/
│   │   └── SKILL.md
│   └── secrets-detector/
│       └── SKILL.md
└── documentation/
    └── doc-generator/
        └── SKILL.md

• Marque o repo como Template no GitHub (Settings → Template repository) para que outros possam criar seus próprios repos a partir do seu com um clique

10. Exemplos de Referência

Skill Kit oficial

O repositório oficial de skills mantido pela comunidade:

🔗 https://github.com/AllanSantos-DV/skill-kit

Contém dezenas de skills, agents e hooks prontos para uso, além do runtime do Neural Link. É a melhor referência para entender a estrutura completa de um skill repo.

Resumo rápido