Agent Skills Framework

Framework modular para adicionar superpoderes aos seus AI agents 🚀

Framework para configuração e gerenciamento de skills para AI agents usando MCP (Model Context Protocol).

📚 O que são Agent Skills?

Agent Skills são capacidades modulares que estendem as funcionalidades de AI agents como o Claude Code. Cada skill adiciona novas integrações, ferramentas e contextos que o agent pode usar.

Skills Disponíveis

• ✅ Azure DevOps - Gerenciamento de work items, projetos, sprints e pipelines
• 🚧 Mais skills em breve...

Este projeto começou com Azure DevOps como skill inicial para estudo e validação da arquitetura.

🚀 Setup Rápido

Opção 1: NPX (🌟 Recomendado para o Time)

Sem precisar clonar o repositório, execute no diretório do seu projeto:

# Setup interativo (escolhe a IA)
npx @systeste/agent-skills

# Ou especifique a IA diretamente
npx @systeste/agent-skills --claude
npx @systeste/agent-skills --gemini
npx @systeste/agent-skills --codex
npx @systeste/agent-skills --copilot

# Limpar configuração e começar do zero
npx @systeste/agent-skills --clear

🤖 IAs Suportadas:

• Claude: Azure DevOps, Context7, Microsoft Learn
• Gemini: Em desenvolvimento
• Codex: Em desenvolvimento
• GitHub Copilot: Azure DevOps MCP

O que acontece:

1. ✅ Você escolhe qual IA usar (ou usa flags --claude/--gemini/--codex/--copilot)
2. ✅ Copia toda a estrutura do Agent Skills personalizada para a IA escolhida:
   • 📁 .claude/ - Configurações específicas da IA
   • 📄 .mcp.json - Servidores MCP configurados
   • 📄 .env.example - Variáveis de ambiente necessárias
   • 📁 skills/ - Documentação das skills disponíveis
   • 📄 Documentação (README, QUICKSTART, etc)
3. ✅ Executa o setup automaticamente (se aplicável)
4. ✅ Configura variáveis de ambiente
5. ✅ Pronto para usar!

Opção 2: Clone Manual

1. Clone o repositório

git clone <url-do-repositorio>
cd agent-skills

2. Configure o Azure DevOps PAT

Opção A: Setup Automático (Recomendado)

.\setup.ps1

O script irá:

1. Verificar se o arquivo .env existe
2. Se não existir, criar a partir do .env.example
3. Solicitar que você adicione seu token
4. Configurar as variáveis de ambiente do sistema

Opção B: Setup Manual

1. Copie o arquivo de exemplo:

   Copy-Item .env.example .env

2. Obtenha seu Personal Access Token:

   • Acesse: https://dev.azure.com/[sua-organizacao]/_usersSettings/tokens
   • Clique em "New Token"
   • Permissões necessárias:
     • Work Items: Read, Write & Manage
     • Project and Team: Read
     • Build: Read
     • Code: Read

3. Edite o arquivo .env e cole seu token:

   AZURE_DEVOPS_PAT=seu-token-aqui

4. Configure a variável de ambiente do sistema:

   # Windows
   [Environment]::SetEnvironmentVariable('AZURE_DEVOPS_PAT', 'seu-token', 'User')

3. Reinicie o terminal

Após configurar a variável de ambiente, feche e abra o terminal novamente.

4. Inicie o Claude Code

claude

📁 Estrutura do Projeto

agent-skills/
├── .claude/
│   └── settings.local.json    # Configurações locais do Claude
├── bin/
│   └── cli.js                 # CLI para NPX
├── skills/
│   └── azure-devops/          # Skill do Azure DevOps
│       ├── .mcp.json          # Config MCP da skill
│       └── README.md          # Docs da skill
├── .env.example               # Template de variáveis de ambiente
├── .env                       # Suas variáveis (não commitado)
├── setup.ps1                  # Script de setup automático
├── package.json               # Configuração NPM
└── README.md                  # Este arquivo

🏗️ Arquitetura

O framework segue uma arquitetura modular:

┌─────────────────────┐
│   Claude Agent      │
│   (AI Assistant)    │
└──────────┬──────────┘
           │
           │ MCP Protocol
           │
┌──────────▼──────────┐
│  Agent Skills       │
│  Framework          │
└──────────┬──────────┘
           │
     ┌─────┴─────┬──────────┐
     │           │          │
┌────▼───┐  ┌───▼────┐  ┌──▼────┐
│ Azure  │  │ Future │  │Future │
│DevOps  │  │Skill 2 │  │Skill 3│
└────────┘  └────────┘  └───────┘

Cada skill é independente e pode ser habilitada/desabilitada conforme necessário.

🔧 Configuração

Trocar de IA

Se você já tem uma IA configurada e quer trocar:

# Limpar tudo e reconfigurar
npx @systeste/agent-skills --clear

# Ou trocar diretamente (o CLI detecta e pergunta se quer trocar)
npx @systeste/agent-skills --gemini

⚠️ O que acontece ao trocar:

• Remove .mcp.json da IA anterior
• Remove .env e .env.example antigos
• Remove configurações específicas em .claude/settings.local.json
• Reconfigura tudo para a nova IA escolhida

Configuração de MCP Servers

Cada IA usa seu próprio formato de configuração MCP:

Claude - .mcp.json:

{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "..."],
      "env": { "AZURE_DEVOPS_PAT": "${AZURE_DEVOPS_PAT}" }
    }
  }
}

Gemini - .gemini/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "TOKEN", "ghcr.io/..."],
      "env": { "TOKEN": "${TOKEN}" }
    }
  }
}

Codex - .codex/config.toml:

[[mcp]]
name = "github"
command = "docker"
args = ["run", "-i", "--rm", "-e", "TOKEN", "ghcr.io/..."]
[mcp.env]
TOKEN = "$TOKEN"

GitHub Copilot - .vscode/mcp.json:

{
  "inputs": [],
  "servers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "@azure-devops/mcp", "sysmanagerdevops", "-d", "core", "work", "work-items"],
      "env": { "AZURE_DEVOPS_PAT": "${AZURE_DEVOPS_PAT}" }
    }
  }
}

Arquivo settings.local.json

Configurações específicas da IA, incluindo:

• Permissões de comandos
• Variáveis de ambiente necessárias
• Servidores MCP habilitados
• Integrações específicas

🛠️ Uso

Depois de configurado, você pode usar o Claude Code para:

• Criar work items
• Listar projetos e teams
• Consultar backlogs e iterações
• Atualizar tasks
• E muito mais!

⚠️ Segurança

• NUNCA commite o arquivo .env (já está no .gitignore)
• Mantenha seu PAT seguro e não compartilhe
• Revogue e regenere o PAT se suspeitar de exposição

🆘 Troubleshooting

MCP não está funcionando

1. Verifique se a variável de ambiente está configurada:

   $env:AZURE_DEVOPS_PAT

2. Se estiver vazia, execute o setup novamente:

   .\setup.ps1

3. Reinicie o terminal

Token inválido

• Verifique se o token tem as permissões corretas
• Regenere o token no Azure DevOps
• Atualize o .env e execute o setup novamente

🔌 Como Adicionar Novas Skills

Quer contribuir com uma nova skill? Siga esta estrutura:

1. Crie o diretório da skill

mkdir skills/nova-skill
cd skills/nova-skill

2. Configure o MCP

Crie um .mcp.json para sua skill:

{
  "mcpServers": {
    "nova-skill": {
      "command": "npx",
      "args": ["-y", "@nome/mcp-server-skill"],
      "env": {
        "SKILL_API_KEY": "${SKILL_API_KEY}"
      }
    }
  }
}

3. Documente a skill

Crie um README.md explicando:

• O que a skill faz
• Como obter credenciais/tokens
• Exemplos de uso
• Troubleshooting

4. Atualize o setup

Adicione variáveis de ambiente necessárias no .env.example

5. Teste localmente

claude

Exemplos de Skills Futuras

• 🔄 GitHub - Gerenciamento de repos, PRs, issues
• 📧 Email - Integração com SMTP/IMAP
• 📊 Jira - Gestão de projetos e tickets
• 🗄️ Databases - Conexão com SQL/NoSQL
• 🔔 Slack/Teams - Notificações e automações
• ☁️ AWS/Azure - Gerenciamento de cloud resources

📦 Publicar no NPM (Para Mantenedores)

1. Login no NPM

npm login

2. Publicar o pacote

npm publish --access public

3. Compartilhar com o time

Envie para o time:

🚀 Setup do Agent Skills agora é só rodar:

npx @systeste/agent-skills

Vai configurar tudo automaticamente!

🔄 Atualizar Versão

# Patch (1.0.0 -> 1.0.1)
npm version patch

# Minor (1.0.0 -> 1.1.0)
npm version minor

# Major (1.0.0 -> 2.0.0)
npm version major

# Publicar
npm publish --access public

📚 Recursos

• Azure DevOps MCP
• Claude Code Docs
• Model Context Protocol