Skill System Foundry

O que Skill System Foundry faz?

Meta-skill para construção de sistemas de habilidades Agnósticos de IA com uma arquitetura de duas camadas (habilidades e funções), modelos, ferramentas de validação e orientação de criação multiplataforma baseada na especificação Agent Skills.

Contexto do Projeto

Este repositório contém uma skill (skill-system-foundry/) e seu conjunto de testes (tests/). A skill é uma meta-skill — seu domínio é construir outras skills. Não é uma aplicação. Não há servidor, banco de dados ou frontend.

Linguagem: Python 3.12+ (apenas biblioteca padrão — sem importações de terceiros no código de produção).

Dependência de desenvolvimento: coverage (apenas medição de cobertura de teste; veja requirements-dev.txt para a versão exata).

Estrutura do repositório:

.
├── AGENTS.md                        ← este arquivo
├── CLAUDE.md                        ← link simbólico para AGENTS.md
├── CONTRIBUTING.md                  ← diretrizes para contribuidores
├── README.md                        ← visão geral do repositório
├── .coveragerc                      ← configuração de cobertura (limiar de 70%, branch)
├── .python-version                  ← versão do Python (veja o arquivo para o valor atual)
├── requirements-dev.txt             ← apenas coverage
├── skill-system-foundry/            ← a meta-skill em si
│   ├── SKILL.md                     ← ponto de entrada (roteador)
│   ├── README.md                    ← documentação da skill
│   ├── capabilities/                ← módulos de capacidade autocontidos
│   │   ├── skill-design/
│   │   │   └── capability.md        ← criar skills, capacidades, funções, manifestos
│   │   ├── validation/
│   │   │   └── capability.md        ← validar skills, auditar sistemas
│   │   ├── migration/
│   │   │   └── capability.md        ← migrar skills planas para o padrão roteador
│   │   ├── bundling/
│   │   │   └── capability.md        ← empacotar skills como bundles zip
│   │   └── deployment/
│   │       ├── capability.md        ← implantar em ferramentas, wrappers, links simbólicos
│   │       └── references/
│   │           └── symlink-setup.md ← comandos de link simbólico específicos da plataforma
│   ├── references/                  ← orientação carregada no contexto sob demanda
│   │   ├── authoring-principles.md  ← consenso de criação multiplataforma
│   │   ├── architecture-patterns.md ← decisões entre padrão standalone vs roteador
│   │   ├── agentskills-spec.md      ← guia de conformidade com a especificação
│   │   ├── tool-integration.md      ← caminhos e implantação específicos de ferramentas
│   │   ├── directory-structure.md   ← layout completo e convenções
│   │   ├── anti-patterns.md         ← erros comuns
│   │   ├── claude-code-extensions.md
│   │   ├── codex-extensions.md
│   │   └── cursor-extensions.md
│   ├── assets/                      ← modelos para scaffolding
│   │   ├── skill-standalone.md
│   │   ├── skill-router.md
│   │   ├── capability.md
│   │   ├── role.md
│   │   └── manifest.yaml
│   └── scripts/                     ← ferramentas de validação, scaffolding, empacotamento
│       ├── lib/                     ← lógica compartilhada (responsabilidade única por módulo)
│       │   ├── configuration.yaml   ← fonte única de verdade para todas as regras de validação
│       │   ├── constants.py         ← carrega YAML, expõe como constantes Python
│       │   ├── validation.py        ← validação compartilhada de nomes/campos
│       │   ├── references.py        ← varredura de referências e travessia de grafo
│       │   ├── bundling.py          ← lógica central de empacotamento
│       │   ├── manifest.py          ← análise e validação de manifesto
│       │   ├── codex_config.py      ← validação de Codex agents/openai.yaml
│       │   ├── yaml_parser.py       ← analisador de subconjunto YAML apenas com stdlib
│       │   ├── frontmatter.py       ← extração de frontmatter YAML
│       │   ├── reporting.py         ← formatação estruturada de saída
│       │   └── discovery.py         ← descoberta de diretórios de skills
│       ├── validate_skill.py        ← validar uma única skill
│       ├── audit_skill_system.py    ← auditar todo o sistema de skills
│       ├── scaffold.py              ← criar novos componentes a partir de modelos
│       └── bundle.py                ← empacotar para distribuição (zip)
├── tests/                           ← conjunto de testes abrangente (veja tests/ para arquivos atuais)
│   ├── helpers.py                   ← utilitários de teste compartilhados
│   └── test_*.py                    ← um arquivo de teste por módulo fonte
├── .agents/                         ← skills internas de desenvolvimento (não distribuídas)
│   └── skills/
│       ├── commit-conventions/       ← formato e convenções de mensagens de commit
│       ├── critique/                ← crítica construtiva de planos e soluções
│       ├── git-release/             ← orientação sobre ciclo de vida de lançamento
│       ├── github-actions/          ← criação e revisão de fluxos de trabalho CI/CD
│       ├── local-code-review/       ← verificações automatizadas locais e análise de diff
│       ├── markdown-docs/           ← aplicação de qualidade de documentação
│       ├── python-scripts/          ← convenções de qualidade de código Python
│       ├── review/                  ← orientação sobre processo de revisão de PR humano
│       ├── shell-scripts/           ← segurança e consistência de scripts shell
│       ├── skill-authoring/         ← consistência de estrutura de meta-skill
│       ├── solution-design/         ← planejamento de solução antes da implementação
│       ├── validate-skill-spec/     ← validação de estrutura e conformidade de especificação
│       └── yaml-config/             ← governança de configuration.yaml
├── .claude/                         ← configuração do Claude Code e links simbólicos de skills
│   └── skills/                      ← links simbólicos para .agents/skills/ para Claude Code
├── .claude-plugin/                  ← configuração do plugin de mercado Claude Code
│   ├── plugin.json
│   └── marketplace.json
└── .github/
    ├── codex/                       ← configuração de revisão Codex
    │   └── review-reference.md      ← orientação de revisão específica do repositório
    ├── scripts/                     ← scripts auxiliares de CI (bash + Python)
    ├── workflows/                   ← GitHub Actions CI/CD
    │   ├── python-tests.yaml        ← testes + cobertura + atualização de badge (ubuntu + windows)
    │   ├── shellcheck.yaml          ← verifica .github/scripts/*.sh
    │   ├── codex-code-review.yaml   ← revisão de PR via codex-ai-code-review-action
    │   └── release.yml              ← cria bundle zip e envia asset de lançamento
    ├── instructions/                ← regras de revisão para Copilot/Codex
    │   ├── markdown.instructions.md ← aplica-se a **/*.md
    │   └── scripts.instructions.md  ← aplica-se a scripts/**/*.py
    ├── copilot-instructions.md      ← orientação de revisão de nível superior
    └── CODEOWNERS                   ← requer aprovação de proprietário do código para .github/

Restrições

Estas restrições são inegociáveis em toda a base de código:

• Apenas biblioteca padrão — sem dependências pip install no código de produção. Scripts devem executar em qualquer lugar onde Python 3.12+ esteja disponível.
• Compatibilidade Python 3.12 — não use funcionalidades do 3.13+.
• Regras de validação em YAML — limites, padrões e palavras reservadas residem em scripts/lib/configuration.yaml. Nunca codifique regras de validação diretamente no Python.
• Apenas os.path — não use pathlib. Não misture os dois.
• Anotações de tipo em todas as assinaturas de função — use genéricos embutidos (list, dict, tuple) e X | None.
• encoding="utf-8" em todas as chamadas open().
• Níveis de erro a partir de constantes — use LEVEL_FAIL, LEVEL_WARN, LEVEL_INFO de lib/constants.py, nunca codifique strings diretamente.
• Funções de validação retornam tuplas (errors, passes) — nunca levante exceções para falhas de validação.
• Scripts shell usam set -euo pipefail e validam variáveis de ambiente no topo com ${VAR:?}.
• Ações fixadas a SHAs de commit — não tags.
• Todos os pontos de entrada de script suportam --json — saída legível por máquina via to_json_output() de lib/reporting.py.

Fluxo de Trabalho de Desenvolvimento

Executando Testes

python -m coverage run -m unittest discover -s tests -p "test_*.py" -v
python -m coverage report

Limiar de cobertura: 70% de cobertura de branch (configurado em .coveragerc). CI executa testes em ubuntu-latest e windows-latest com Python 3.12.

Validando a Meta-Skill

cd skill-system-foundry
python scripts/validate_skill.py . --allow-nested-references --verbose
python scripts/audit_skill_system.py .

A flag --allow-nested-references é necessária porque esta meta-skill usa intencionalmente referências aninhadas. Um aviso sobre um diretório skills/ ausente da auditoria é esperado neste repositório de distribuição.

Verificando Scripts Shell

shellcheck .github/scripts/*.sh

Formato da Mensagem de Commit

Atualizar <componente> e <componente>
Adicionar <nova-coisa> em <local>
Corrigir <problema> em <componente>

Regras de Arquitetura

O sistema de habilidades tem exatamente duas camadas:

• Habilidades — conhecimento canônico, Agnóstico de IA. Standalone para tarefas focadas, roteador para domínios complexos.
• Funções — contratos de orquestração compondo 2+ habilidades com responsabilidade, autoridade, restrições e regras de transferência.

As dependências fluem estritamente para baixo: funções → habilidades → capacidades. Nunca o inverso. Capacidades são opcionais e só se justificam quando 3+ operações distintas têm acionadores mutuamente exclusivos.

Organização do Código

• Pontos de entrada (scripts/*.py) — wrappers finos: análise de argumentos, formatação de saída, sys.exit(). Delegam tudo para scripts/lib/.
• Módulos de biblioteca (scripts/lib/*.py) — lógica de domínio. Sem print() ou sys.exit() exceto em helpers de saída dedicados (reporting.py).
• Constantes (scripts/lib/constants.py) — constantes estruturais em Python, regras de validação carregadas de configuration.yaml. Todos os valores YAML são retornados como strings pelo analisador personalizado — converta com int() em constants.py.
• Testes (tests/) — um arquivo de teste por módulo fonte. unittest.TestCase com nomes de classe descritivos agrupados por funcionalidade. Separadores de seção (# ===...) para clareza visual.

Padrões de Documentação

• Concisão em primeiro lugar — adicione apenas contexto que o modelo ainda não possui.
• Terceira pessoa nas descrições de habilidades — "Valida habilidades" não "Eu valido habilidades".
• Um termo por conceito — sem mistura de sinônimos dentro ou entre arquivos.
• Divulgação progressiva — SKILL.md com menos de 500 linhas, detalhes em references/, referências cruzadas com profundidade máxima de um nível.
• Frontmatter — bloco escalar dobrado (>) para descrições multilinha, caracteres especiais entre aspas.
• Marcação de nível de erro — [spec] para regras de especificação, [platform: X] para restrições de plataforma, [foundry] para convenções.

Orientação de Revisão

Regras de revisão detalhadas estão em .github/instructions/:

Arquivo	Aplica-se a	Foco
.github/copilot-instructions.md	Todos os arquivos	Conformidade com a especificação Agent Skills, arquitetura
.github/instructions/markdown.instructions.md	**/*.md	Qualidade de documentação, acionadores de descrição
.github/instructions/scripts.instructions.md	scripts/**/*.py	Qualidade de código, apenas stdlib, anotações de tipo

Validação automatizada (validate_skill.py, audit_skill_system.py) lida com muitas verificações de frontmatter, nomenclatura, contagem de linhas e estruturais. Revisão manual ainda verifica convenções de referência de arquivo markdown (incluindo caminhos relativos à raiz da skill), validade de caminhos, divulgação progressiva, qualidade de descrição, justificativa arquitetural e consistência semântica.

Processo de Lançamento

Versão reside no frontmatter de skill-system-foundry/SKILL.md (metadata.version). Tags espelham como vX.Y.Z. O fluxo de trabalho release.yml cria automaticamente um bundle zip e o envia como asset de lançamento. Execute validação completa e testes antes de marcar a tag.