skills-general

Biblioteca TypeScript das agent skills de engenharia do Leandro. O payload são pastas SKILL.md no formato Agent Skills. O pacote npm cataloga, valida e aponta o caminho dessas pastas — quem executa a skill é o agente (Cursor, Claude Code, Codex, etc.).

Repositório: leandrobudaumoraes/skills-general. Pacote: @leandrobudaumoraes/skills-general.

O que entra (e o que não entra)

Publicadas neste repositório e no npm:

| Skill | Grupo | Uso | | --- | --- | --- | | revisar-codigo | Engenharia | Bar de qualidade, segurança e performance | | analisar-ui-ux | Engenharia | Identidade visual, fluxo e estados de UI | | criar-pr | Engenharia | Abrir pull request com corpo para gestor e técnico | | analise-jira | Jira | Análise híbrida de ticket → chat → Confluence | | analise-jira-frontend | Jira | Análise só frontend | | decisao-jira | Jira | Registrar a opção escolhida / ADR | | refinar-jira | Jira | Quebrar história em subtarefas | | implementar-jira | Jira | Implementar lote aprovado |

Não entram as skills pessoais (medico-pessoal, terapeuta-espiritual, coach-carreira, assistente-notion, assistente-planejamento). Elas continuam só em ~/.cursor/skills.

As skills de Jira trazem destinos de Confluence do autor (destino.md). Em outro time, sobrescreva no projeto ou não instale o grupo Jira.

Requisitos

• Node.js 22 ou superior
• Para instalar no agente: npx (vem com o Node)
• Para desenvolver este repo: pnpm 10

Como usar

Há três formas. A primeira é a que um agente precisa no dia a dia.

1. Instalar no agente (recomendado)

O CLI skills copia/symlink as pastas para o Cursor, Claude Code, Codex e outros.

npx skills add leandrobudaumoraes/skills-general

Uma skill só:

npx skills add leandrobudaumoraes/skills-general -s revisar-codigo

Global (todos os projetos da máquina):

npx skills add leandrobudaumoraes/skills-general -g

Depois disso o agente passa a ver name + description no startup e lê o SKILL.md quando o pedido combina. Exemplos de pedido:

• “revisa esse diff”
• “analisa o KAN-12”
• “abre a PR”

2. Instalar via npm + skills-npm

Quando o projeto já usa Node, as skills podem viajar no node_modules e o skills-npm cria os symlinks para o agente.

pnpm add -D @leandrobudaumoraes/skills-general skills-npm
pnpm skills-npm setup

O setup liga um prepare no package.json e sincroniza de novo a cada pnpm install. Convenção: o pacote publica skills/*/SKILL.md na raiz.

3. API TypeScript

Para listar, validar ou achar o diretório no disco (geradores, CI, docs):

import {
  getSkill,
  listSkills,
  skillNames,
  skillsRoot,
  validateCatalog,
} from '@leandrobudaumoraes/skills-general'

skillNames
// ['revisar-codigo', 'analisar-ui-ux', ...]

const review = getSkill('revisar-codigo')
review.group       // 'engineering'
review.description // texto do frontmatter
review.directory   // URL da pasta no pacote instalado

listSkills()
validateCatalog()  // { ok, issues }
skillsRoot()       // URL de .../skills/

O TypeScript só aceita os nomes literais de skillNames. Nomes pessoais (medico-pessoal, etc.) não compilam.

CLI do pacote

npx @leandrobudaumoraes/skills-general list
npx @leandrobudaumoraes/skills-general validate
npx @leandrobudaumoraes/skills-general path
npx @leandrobudaumoraes/skills-general path revisar-codigo

validate sai 0 e imprime ok se cada pasta em skills/ passa na spec (frontmatter, name = diretório, description 1–1024 caracteres) e não há skill fora do catálogo.

Estrutura do repositório

skills/                 payload publicado (uma pasta por skill)
src/                    catálogo, parse, validação, CLI
scripts/sync-skills.ts  copia ~/.cursor/skills → skills/ (allowlist)
skills.sh.json          agrupamento no skills.sh

Cada skill segue a spec:

skills/revisar-codigo/
├── SKILL.md
├── criterios.md        # referência sob demanda
└── scripts/            # opcional

Desenvolver

pnpm install
pnpm test
pnpm lint
pnpm typecheck
pnpm validate
pnpm build

Atualizar o payload a partir das skills locais de engenharia (nunca copia as pessoais):

pnpm sync

Fonte: ~/.cursor/skills/{nome}. Destino: skills/{nome}. A allowlist é skillNames em src/types.ts.

Publicar no npm

O GitHub Actions em .github/workflows/release.yml publica quando você empurra uma tag v*.

pnpm version patch   # ou minor / major
git push origin main --follow-tags

Uma vez por conta npm: criar o scope @leandrobudaumoraes, criar o pacote placeholder e ligar Trusted Publishing neste repositório com o workflow release.yml. Não use NPM_TOKEN de longa duração.

Licença

MIT