@sysmanager/ai-skills

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 @sysmanager/ai-skills install --skill ado-workflow --target claude

Pronto. Sem configuracao manual, sem copiar arquivos.

Comandos

install

Instala skills no seu projeto.

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

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

# Escolhe tudo interativamente (fallback)
npx @sysmanager/ai-skills install

Targets disponiveis: claude | codex | gemini | copilot

list

Lista todas as skills disponiveis no catalogo.

npx @sysmanager/ai-skills list

--clear

Remove todas as configuracoes de AI do projeto.

npx @sysmanager/ai-skills --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

• O CLI le as skills de skills/ e os templates MCP de mcps/
• Gera a configuracao no formato correto para o target escolhido
• Faz merge inteligente se ja existir configuracao (brownfield)
• 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

CI/CD

O projeto usa Azure Pipelines com publicacao automatica no NPM a cada merge na main.

Stage	Trigger	O que faz
CI	push em main ou feature/*, PRs para main	Instala dependencias, compila TypeScript, publica artefato dist/
CD	merge na main (apos CI passar)	Bumpa a versao patch, publica no NPM, commita package.json atualizado com tag git

O bump de versao so ocorre se a versao ainda nao estiver publicada no registry — evitando duplicatas em runs paralelos.

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:

• Verifique se as variaveis estao no .env e preenchidas
• Reinicie o terminal / AI agent
• 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