repo-auditor
Skill de auditoria inicial e continua do repositorio. Use quando precisar mapear stack real, convencoes, assets, testes, docs, riscos e pontos de integracao antes de executar outras skills. O resultado deve ser persistido em markdown reutilizavel para reduzir releitura e economizar tokens. Trigger em: "repo audit", "auditar repositorio", "mapear stack do projeto", "harnessability score", "repo-audit", "auditoria de repo", "fotografia do repo", "current.md", "mapear convencoes do projeto", "inventariar o codebase".
57
67%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/18-repo-auditor/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong skill description that clearly defines its purpose (repository auditing and mapping), specifies concrete deliverables (stack, conventions, assets, tests, docs, risks, integration points persisted in markdown), and provides explicit trigger guidance with a comprehensive list of natural trigger terms. The description is well-structured, concise, and distinctive enough to avoid conflicts with other skills.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: mapear stack real, convenções, assets, testes, docs, riscos, pontos de integração. Also mentions persisting results in reusable markdown to reduce re-reading and save tokens. | 3 / 3 |
Completeness | Clearly answers both 'what' (audit repository to map stack, conventions, assets, tests, docs, risks, integration points and persist in markdown) and 'when' (explicit 'Use quando' clause plus a dedicated 'Trigger em' list with specific trigger phrases). | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural trigger terms including multiple variations: 'repo audit', 'auditar repositorio', 'mapear stack do projeto', 'harnessability score', 'inventariar o codebase', 'fotografia do repo', 'current.md'. These are terms users would naturally say when needing this skill. | 3 / 3 |
Distinctiveness Conflict Risk | Clearly occupies a distinct niche as an initial/continuous repository audit skill. The specific triggers like 'repo audit', 'harnessability score', 'current.md', and 'inventariar o codebase' are highly distinctive and unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill attempts to be comprehensive but suffers from significant verbosity — the harnessability scoring tables, recommend-automation mode with its five sub-sections, and split catalog could all be separate referenced files, keeping the main SKILL.md lean. The actionability is moderate with good detection signals but no executable code. The workflow lacks clear sequential steps with validation checkpoints for what is essentially a multi-step audit process.
Suggestions
Extract the Harnessability Score tables, Recommend-Automation mode, and Split Catalog into separate referenced files (e.g., `docs/skill-guides/harnessability.md`, `docs/skill-guides/recommend-automation.md`) to reduce the main SKILL.md to under 80 lines.
Add a clear numbered workflow section at the top: 1) Check for existing audit, 2) Scan repo structure, 3) Calculate harnessability score, 4) Generate splits, 5) Validate output completeness, 6) Persist and handoff — with explicit validation checkpoints.
Replace abstract detection descriptions with concrete executable commands or tool invocations (e.g., `find . -name 'tsconfig.json' -exec grep -l 'strict.*true' {} +` or specific tool calls Claude should use).
Remove content Claude already knows — e.g., explanations of what MCP servers do, what hooks are for, general descriptions of CI/CD tools — and focus only on project-specific decision criteria.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~250+ lines. It includes extensive tables for harnessability scoring, automation recommendations, MCP servers, slash commands, and subagents that could easily be split into referenced files. Much of this content (what hooks do, what MCP servers are, general recommendations) is knowledge Claude already has. The 'Recommend-Automation' section alone is massive and should be a separate reference file. | 1 / 3 |
Actionability | The skill provides concrete detection signals (e.g., check for `tsconfig.json` with `strict:true`, look for `.eslintrc*`), clear output formats with markdown examples, and specific file paths. However, there are no executable code/commands — no actual scripts to run, no CLI invocations for detection, and the detection logic is described rather than implemented. The split detection criteria are useful but still somewhat abstract. | 2 / 3 |
Workflow Clarity | The skill describes what to do (detect, score, persist, split) but lacks a clear sequential workflow with numbered steps and validation checkpoints. There's no explicit 'Step 1: Read existing audit, Step 2: Scan repo, Step 3: Validate findings, Step 4: Persist' flow. The 'Regras do Split' section has some ordering logic but the overall process is scattered across multiple sections without a clear execution sequence. Missing validation steps for the audit output itself. | 2 / 3 |
Progressive Disclosure | The skill references several external files (`policies/harness-categories.md`, `docs/inspiration/harness-engineering.md`, `docs/skill-guides/repo-auditor.md`, `templates/audit.md`, various policies) which is good progressive disclosure in principle. However, no bundle files are provided to verify these exist, and the SKILL.md itself is a monolithic wall containing massive tables and the entire recommend-automation specification inline — content that should clearly be in referenced sub-files. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
81%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 9 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
allowed_tools_field | 'allowed-tools' contains unusual tool name(s) | Warning |
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 9 / 11 Passed | |
- Repository
- felvieira/claude-skills-fv
- Commit
7577622
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.