skill-audit
- Repo stars 0
- Author updated Live
- Author repo skills-registry
- Domain
- Security
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- Python >=3.8
- Permissions
-
- Read-only
- Shell exec
- Write / modify
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: skill-audit
description: Audits a Claude Code / Agent SDK skill (or folder of skills) against 10 QA Use when this capabil…
category: security
runtime: Python
---
# skill-audit output preview
## PART A: Task fit
- Use case: Audits a Claude Code / Agent SDK skill (or folder of skills) against 10 QA Use when this capability is needed. name: skill-audit checks to verify it will trigger and execute correctly in any LLM (Claude, GPT, Gemini). Ativa quando o usuário diz "audit my skill", "roda skill-audit", runs entirely locally; runs on Python >=3.8. Works with Claude Code, Curso….
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “When to Use / When NOT to Use / Inputs” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Audits a Claude Code / Agent SDK skill (or folder of skills) against 10 QA Use when this capability is needed. name: skill-audit checks to verify it will trigger and execute correctly in any LLM (Claude, GPT, Gemini). Ativa quando o usuário diz "audit my skill", "roda skill-audit", runs entirely locally; runs on Python >=3.8. Works with Claude Code, Curso…”.
- **02** When the source has headings, the agent prioritizes “When to Use / When NOT to Use / Inputs” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, run shell commands, write/modify files; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, run shell commands, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, run shell commands, write/modify files.
Start with a small task and check whether the result follows “When to Use / When NOT to Use / Inputs”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: skill-audit
description: Audits a Claude Code / Agent SDK skill (or folder of skills) against 10 QA Use when this capabil…
category: security
source: tomevault-io/skills-registry
---
# skill-audit
## When to use
- Audits a Claude Code / Agent SDK skill (or folder of skills) against 10 QA Use when this capability is needed. name: s…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “When to Use / When NOT to Use / Inputs” and keep inference separate from source facts.
- read files, run shell commands, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "skill-audit" {
input -> user goal + target files + boundaries + acceptance criteria
context -> When to Use / When NOT to Use / Inputs
rules -> SKILL.md triggers / order / output contract
runtime -> Python | read files, run shell commands, write/modify files | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} name: skill-audit
description: >
Audits a Claude Code / Agent SDK skill (or folder of skills) against 10 QA
checks to verify it will trigger and execute correctly in any LLM (Claude,
GPT, Gemini). Ativa quando o usuário diz "audit my skill", "roda skill-audit",
"verifica se essa skill funciona", "check skill quality", "skill-audit ./my-skill",
"minha skill não dispara", "migrei do Claude antigo e quebrou", ou colar path
de um SKILL.md. Retorna score 0-10 por skill, issues priorizados, e sugestões
de conserto. NÃO use para: criar uma skill nova do zero (use criar-skill
ou skill-creator); executar a skill alvo; refatorar código genérico.
type: skill
category: meta
status: ATIVO
version: 1.0
created: 2026-04-19
last_reviewed: 2026-04-19
estimated_time: 2min
model_compatible: [claude-sonnet-4, claude-opus-4, gpt-5, gpt-4o, gemini-pro]
skill-audit
Auditoria estática de SKILL.md contra o padrão V3 (LLM-friendly). Roda 10 QA
checks, detecta issues mecânicos e semânticos, entrega report priorizado. Útil
especialmente pra quem migrou de Claude pre-4.5 — skills antigas costumam
funcionar só no contexto do autor, não em agentes externos.
When to Use
Aciona quando:
- Usuário tem uma skill que "não dispara" ou "não executa direito"
- Migrou de Claude 3.x / 4.0 pra 4.6+ e viu comportamento quebrado
- Quer rodar a skill em GPT-5, Gemini, ou outro LLM que não seja Claude
- Está criando skills em massa (ex: para alunos, time, comunidade)
- Quer priorizar quais skills da coleção conserta primeiro
Exemplos literais de mensagens:
- "roda skill-audit em skills/my-skill/SKILL.md"
- "minha skill não dispara no GPT"
- "audita essa pasta de skills pra mim"
- "skill-audit ./skills"
- "por que essa skill funciona no Claude mas não no Gemini?"
When NOT to Use
NÃO aciona se:
- Usuário quer CRIAR uma skill do zero → usar
criar-skillouskill-creator - Usuário quer EXECUTAR a skill auditada → rodar a skill diretamente
- Usuário quer auditoria de segurança (OWASP, secrets em produção) → outra ferramenta
- Arquivo alvo não é
SKILL.md(ex: script Python, README) → refatoração genérica
Inputs
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| path | string | ✅ | Path de um SKILL.md OU pasta contendo subpastas com SKILL.md (recursivo) |
| format | string | ❌ | markdown (default) ou json — formato do report |
Outputs
| Campo | Tipo | Descrição |
|---|---|---|
| score | int 0-10 | Quantos dos 10 QA checks a skill passa |
| issues | array | Lista priorizada de problemas (ex: desc_no_triggers, examples_too_few) |
| by_category | object | Score médio e passing rate por categoria de skill |
| report | markdown | Report completo com ranking + detalhamento por skill |
Formato de entrega: arquivo markdown em ./audit-results.md + resumo no terminal.
Workflow
- Validar input — path existe? É arquivo
.mdou diretório? - Coletar SKILL.md files
- SE path aponta pra arquivo
.md→ lista única - SENÃO →
glob **/SKILL.mdrecursivo no diretório
- SE path aponta pra arquivo
- Para cada SKILL.md:
- Parsear frontmatter YAML (
---...---) - Split do body em seções H2 (ignorando H2 dentro de code fences ``` ou ~~~)
- Rodar os 10 QA checks
- Registrar score + issues + contagens
- Parsear frontmatter YAML (
- Agregar resultados — score médio, distribuição, issues mais comuns
- Gerar report markdown em
./audit-results.mdcom:- Sumário global
- Distribuição de scores
- Issues por frequência
- Top 30 skills que mais precisam conserto
- Detalhamento por skill
- Imprimir resumo no terminal — total, score médio, passing ≥7
Os 10 QA checks
- Nome em kebab-case e bate com pasta
- Description: 50+ palavras, terceira pessoa, 5+ trigger phrases, negative boundaries
- Cada passo do Workflow é ação única, imperativa, não-ambígua
- 2+ exemplos concretos (input real → output real)
- Edge Cases cobertos (3+ condições)
- Output Format explicitamente definido
- Zero linguagem vaga (lista de palavras banidas em
references/qa-checklist.md) - Negative boundaries na seção
## When NOT to Use - Zero credenciais hardcoded (secrets, API keys, tokens)
- Pasta
evals/evals.jsonexiste com 2+ casos
Edge Cases
- Se path não existe → exit 1 com mensagem "Path não encontrado: {path}"
- Se diretório vazio (0 SKILL.md) → exit 0 com mensagem "Nenhum SKILL.md encontrado em {path}"
- Se SKILL.md sem frontmatter YAML → score 0, issue
missing_frontmatter - Se YAML inválido → score 0, issue
yaml_parse_error - Se pasta
evals/existe mas semevals.json→ issueno_evals_folder - Se SKILL.md muito grande (>350 linhas) → warning
long, sugere mover conteúdo parareferences/ - Se placeholder ref (
link,url,path) em markdown link → ignorado (não conta como broken ref)
Examples
Example 1 — Auditar uma skill única
Input real: skill-audit ./my-skill/SKILL.md
Workflow executado:
- Valida que
./my-skill/SKILL.mdexiste - Parseia YAML — encontra
name: my-skill, description de 32 palavras - Body split: tem
## When to Use, falta## When NOT to Use - Roda 10 checks: description short (32w<50), no negatives, no evals folder, só 1 Example
- Gera report
Output real:
skill-audit: 1 skill analisada
my-skill — 6/10 (232L, 32w desc, 4 triggers, 1 ex, 4 edge, evals ✗)
Issues: desc_too_short(32w), desc_no_negatives, examples_too_few(1), no_evals_folder
Report: ./audit-results.md
Example 2 — Auditar pasta inteira (edge: várias skills)
Input real: skill-audit ~/my-claude-skills/
Workflow executado:
- Valida que
~/my-claude-skills/é diretório - Glob encontra 12
SKILL.md - Para cada: parseia + checks + score
- Agrega: score médio 7.1, 4/12 passing ≥7
- Report priorizado: pior primeiro
Output real:
skill-audit: 12 skills analisadas
Score médio: 7.1/10
Passing (≥7): 4/12 (33%)
Top 3 issues mais comuns:
desc_no_negatives (12, 100%)
no_evals_folder (9, 75%)
desc_too_short (7, 58%)
Worst offenders:
1. legacy-skill-x — 3/10
2. migrated-from-gpt — 4/10
3. old-claude35-skill — 5/10
Report: ./audit-results.md
Dependencies
- Runtime: Python 3.8+
- Libs: stdlib only (re, json, pathlib, argparse, collections)
- APIs: nenhuma — 100% estático/offline
- Files:
templates/SKILL-TEMPLATE.md+references/qa-checklist.md(read-only) - Outras skills: nenhuma — ferramenta standalone
Errors & Recovery
| Erro | Causa provável | Fix |
|---|---|---|
Path não encontrado |
Path inválido ou digitado errado | Verificar path absoluto; usar ls {path} pra confirmar |
yaml.YAMLError |
Frontmatter mal formado | Abrir SKILL.md, verificar indentação e fechamento --- |
UnicodeDecodeError |
SKILL.md em encoding não-UTF8 | Salvar como UTF-8 no editor |
ModuleNotFoundError: yaml |
PyYAML ausente | pip3 install pyyaml |
| Report não gerado | Permissão de escrita em ./audit-results.md |
Rodar de diretório com permissão de escrita |
Notes
Sobre o score: 7/10 é o mínimo aceitável pra considerar uma skill "trigger-confiável" em LLMs externos. 10/10 é ideal. Abaixo de 7 geralmente significa que a skill foi escrita em prosa livre e não em contrato executável — formato comum em skills pre-V3.
Sobre evals.json: o check 10 não valida conteúdo dos evals, só presença do arquivo
e estrutura mínima (2+ casos com prompt e expected_output). Qualidade dos evals é
trabalho do autor da skill, não do audit.
Limitações conhecidas:
- Não audita qualidade semântica do workflow (se os passos fazem sentido pro domínio)
- Não executa a skill (só análise estática)
- Heurísticas de trigger phrase podem dar falso positivo em descriptions técnicas densas — revisar issues manualmente quando score for borderline (6-7)
Changelog
- v1.0 (2026-04-19): Versão inicial. 10 QA checks baseados no padrão V3. Deriva de auditoria em 119 skills do workspace Amora (score médio 5.9 → 10.0).
Source: AlexandreBozo/brain — distributed by TomeVault.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review