AI Skills Library

Este repositório contém um conjunto estruturado de Skills em Markdown para ensinar agentes de IA a executar tarefas de forma padronizada, previsível e controlada.

Cada Skill descreve:

• Objetivo claro
• Contexto de uso
• Pré-requisitos
• Passos executáveis
• Comandos
• Restrições
• Decisões arquiteturais

O objetivo é reduzir ambiguidade e impedir improvisações.

Documentos Principais

• Índice de skills: SKILLS.md
• Regras globais de agentes: AGENTS.md
• Backlog de skills: BACKLOG.md

---

🧱 Convenções Globais

As convenções globais ficam centralizadas em AGENTS.md. Use este arquivo como fonte única de verdade para regras de comportamento e restrições.

---

📐 Estrutura Base de uma Skill

Cada skill deve ter um SKILL.md com:

• Frontmatter YAML obrigatório:
  • name
  • description (o que faz + quando usar)
• Corpo em Markdown com instruções operacionais para execução da skill.

Estrutura mínima da pasta:

<skill-name>/
  SKILL.md

Recursos opcionais (quando agregam valor):

<skill-name>/
  SKILL.md
  scripts/
  references/
  templates/

Seções sugeridas para o corpo do SKILL.md (adaptar conforme o caso):

• Objetivo
• Quando usar
• Pré-requisitos
• Passos
• Comandos
• Padrões e decisões
• Restrições

Princípios de autoria:

• Ser conciso e evitar conteúdo redundante.
• Definir o grau de liberdade adequado (instrução aberta vs. sequência prescritiva).
• Usar progressive disclosure: manter o fluxo principal no SKILL.md e mover detalhes variantes para references/.

---

Inventário de Skills

Para lista de skills ativas, status e categorias, use somente SKILLS.md. O README.md descreve convenções e objetivos gerais, sem replicar o inventário.

---

Sincronização de Skills

Este repositório usa apenas dois scripts de sync:

• scripts/sync_skills.sh: engine central de sincronização (recebe --target)
• scripts/sync_targets.sh: mapeia os destinos conhecidos (codex, agents, claude, antigravity, all) e invoca o script central

Uso:

./scripts/sync_targets.sh codex
./scripts/sync_targets.sh agents
./scripts/sync_targets.sh claude
./scripts/sync_targets.sh antigravity
./scripts/sync_targets.sh all

Pré-visualização (sem alterar nada):

./scripts/sync_targets.sh codex --dry-run
./scripts/sync_targets.sh agents --dry-run
./scripts/sync_targets.sh claude --dry-run
./scripts/sync_targets.sh antigravity --dry-run
./scripts/sync_targets.sh all --dry-run

Comportamento:

• Cria links para diretórios com SKILL.md e para compartilhados permitidos (por padrão, _shared).
• Aceita --shared-dir <name> para incluir outros diretórios compartilhados sem SKILL.md.
• Cria links apenas para entradas que ainda não existem no destino.
• Mantém skills já instaladas manualmente.
• Ignora caminhos existentes para evitar alterações destrutivas.
• Repara symlink quebrado por padrão (use --no-relink-broken para desativar).

---

🎯 Objetivo do Sistema

Criar um conjunto modular de instruções reutilizáveis para:

• Padronizar projetos
• Automatizar criação de aplicações
• Controlar decisões técnicas
• Reduzir inconsistências

Cada nova capability deve virar uma Skill.