npm package: @sysmanager/ai-skills
Description: Agent Skills Framework - Easy setup for AI agent capabilities and integrations (Claude, Gemini, Codex, GitHub Copilot)
Author: Sys Manager
Latest version: 1.0.20

# SYS AI Skills

> Skills para turbinar seus agentes de codigo

[![NPM Version](https://img.shields.io/npm/v/@sysmanager/ai-skills)](https://www.npmjs.com/package/@sysmanager/ai-skills)

## 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

```bash
npx @sysmanager/ai-skills install --skill ado-workflow --target claude
```

Pronto. Sem configuracao manual, sem copiar arquivos.

## Comandos

### install

Instala skills no seu projeto.

```bash
# 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.

```bash
npx @sysmanager/ai-skills list
```

### --clear

Remove todas as configuracoes de AI do projeto.

```bash
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

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

```bash
mkdir skills/minha-skill
```

### 2. Crie o SKILL.md com frontmatter

```markdown
---
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)

```bash
# 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

```bash
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:**
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