SYS AI Skills

Skills para turbinar seus agentes de codigo

O que e isso?

AI Skills sao capacidades modulares que voce instala no seu projeto para estender AI agents (Claude, Gemini, Codex, GitHub Copilot). Cada skill adiciona integracoes, workflows e contexto que o agent pode usar.

Instalacao

npx @sysvv/ai-skill install --skill ado-workflow --target claude

Pronto. Sem configuracao manual, sem copiar arquivos.

Comandos

install

Instala skills no seu projeto.

# Direto, sem perguntas
npx @sysvv/ai-skill install --skill ado-workflow --target claude

# Escolhe a skill interativamente
npx @sysvv/ai-skill install --target claude

# Escolhe tudo interativamente (fallback)
npx @sysvv/ai-skill install

Targets disponiveis: claude | codex | gemini | copilot

list

Lista todas as skills disponiveis no catalogo.

npx @sysvv/ai-skill list

--clear

Remove todas as configuracoes de AI do projeto.

npx @sysvv/ai-skill --clear

Skills disponiveis

| Skill | Descricao | MCP | |-------|-----------|-----| | ado-workflow | Workflow de desenvolvimento integrando work items do Azure DevOps com commits Git e gestao de estados | azure-devops | | git-cli | Operacoes Git universais — status, commits inteligentes, push seguro e sync completo | — |

Como funciona

1. O CLI le as skills de skills/ e os templates MCP de mcps/
2. Gera a configuracao no formato correto para o target escolhido
3. Faz merge inteligente se ja existir configuracao (brownfield)
4. Cria o .env com as variaveis necessarias

O que e gerado por target

| Target | Skills | Config MCP | |--------|--------|------------| | claude | .claude/skills/{id}/prompts/ | .mcp.json | | gemini | .gemini/skills/{id}/references/ | .gemini/settings.json | | codex | .codex/skills/{id}/references/ | .codex/config.toml | | copilot | .github/skills/{id}/references/ | .vscode/mcp.json |

Estrutura do projeto

skills/              # Fonte de verdade das skills
  ado-workflow/
    SKILL.md         # Frontmatter + instrucoes
    prompts/         # Templates de operacoes
  git-cli/
    SKILL.md
    prompts/
mcps/                # Templates de servidores MCP
  azure-devops.mcp.json
schemas/             # JSON Schema para validacao
src/                 # TypeScript source
  index.ts           # Entry point do CLI
  core/
    frontmatter.ts   # Parser de YAML frontmatter
    registry.ts      # Descoberta de skills
    skill.ts         # Carregamento + template rendering
    mcp.ts           # Strategy: gera config por target
    render.ts        # Engine de {{variaveis}}

Criar uma nova skill

1. Crie o diretorio

mkdir skills/minha-skill

2. Crie o SKILL.md com frontmatter

---
id: minha-skill
name: Minha Skill
version: 1.0.0
description: What this skill does.
description_pt: O que essa skill faz.
category: productivity
language: en
requires:
  mcp: [nome-do-mcp]
  env: [API_KEY]
tags: [tag1, tag2]
---

# Instrucoes da skill aqui...

3. Adicione o MCP template (se necessario)

# mcps/nome-do-mcp.mcp.json
{
  "name": "nome-do-mcp",
  "description": "Descricao do MCP.",
  "transport": "stdio",
  "command": "npx",
  "args": ["-y", "@org/mcp-server"],
  "env": { "API_KEY": "${API_KEY}" }
}

4. Teste

npm run build
node dist/index.js list
node dist/index.js install --skill minha-skill --target claude

Publicar

npm login
npm version patch
npm publish --access public

Seguranca

• NUNCA commite o .env (ja esta no .gitignore)
• Tokens sao referenciados via ${VAR}, nunca hardcoded
• O CLI so adiciona variaveis faltantes no .env, nunca sobrescreve

Troubleshooting

MCP nao funciona:

1. Verifique se as variaveis estao no .env e preenchidas
2. Reinicie o terminal / AI agent
3. Verifique se o MCP server esta acessivel: npx @azure-devops/mcp --help

Skill nao aparece no list:

• Verifique se existe skills/{id}/SKILL.md com frontmatter valido