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".

Quality

67%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Fix and improve this skill with Tessl

tessl review fix ./skills/18-repo-auditor/SKILL.md

Quality

Content

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 — it packs what should be 3-4 separate reference documents into a single body. The harnessability scoring system and automation recommendation engine are well-conceived features but their full specification belongs in referenced files, not inline. The skill lacks a clear step-by-step execution workflow and executable detection logic, relying instead on descriptive tables and prose.

Suggestions

Extract the Harnessability Score table, Recommend-Automation section, and Output Split catalog into separate referenced files (e.g., `docs/skill-guides/harnessability.md`, `docs/skill-guides/recommend-automation.md`) and keep only a 2-3 line summary with pointer in the main body.

Add a clear numbered workflow sequence (e.g., '1. Check for existing audit → 2. Scan repo structure → 3. Detect stack signals → 4. Calculate harnessability → 5. Generate splits → 6. Validate output completeness → 7. Persist') with explicit validation checkpoints.

Replace detection prose in tables with concrete tool invocations (e.g., `find . -name 'tsconfig.json' -exec grep -l 'strict.*true' {} +` or `Bash: ls .eslintrc* 2>/dev/null`) to make the skill more actionable.

Remove explanatory text that Claude already knows (e.g., what MCP servers do, what subagents are for, what hooks accomplish) and keep only the mapping logic from detected signals to recommendations.

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 (like explaining what hooks do, what MCP servers are for) assumes Claude doesn't know things it already does. The 'Recommend-Automation' section alone is massive and should be a separate reference file.	1 / 3
Actionability	The skill provides concrete detection patterns (e.g., check for `tsconfig.json` with `strict:true`, look for `.eslintrc*`) and clear output formats with markdown examples. However, there are no executable code snippets or commands — detection logic is described in prose/tables rather than as runnable scripts or specific tool invocations. The guidance is specific but not copy-paste executable.	2 / 3
Workflow Clarity	The skill describes when to audit, what to output, and persistence rules, but lacks a clear numbered step-by-step workflow for actually performing the audit. There's no explicit sequence like 'Step 1: Read existing audit, Step 2: Scan file tree, Step 3: Detect stack...' with validation checkpoints. The 'When to Reaudit' section and token economy rules hint at validation but don't form a coherent feedback loop.	2 / 3
Progressive Disclosure	The skill references several external files (`policies/harness-categories.md`, `docs/skill-guides/repo-auditor.md`, `templates/audit.md`, `policies/handoffs.md`, etc.) which is good progressive disclosure design. However, the body itself is monolithic — the harnessability scoring table, recommend-automation section, output split catalog, and detection rules are all inline when they should be in referenced files. The references exist but the content that should be delegated to them remains in the main body.	2 / 3
	Total	7 / 12 Passed

Description

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 (initial and continuous repository auditing), specifies concrete actions (mapping stack, conventions, assets, tests, docs, risks, integration points), and provides explicit trigger guidance with a comprehensive list of natural trigger terms in both Portuguese and English. The description also adds useful context about when to use it (before other skills) and what to do with results (persist in markdown), making it highly actionable for skill selection.

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions: mapear stack real, convenções, assets, testes, docs, riscos e 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' (before executing other skills, with explicit trigger terms listed). The 'Use quando' clause and 'Trigger em' list make this very complete.	3 / 3
Trigger Term Quality	Excellent coverage of natural trigger terms including multiple variations: 'repo audit', 'auditar repositorio', 'mapear stack do projeto', 'harnessability score', 'auditoria de repo', 'fotografia do repo', 'current.md', 'inventariar o codebase'. These cover both Portuguese and English terms users would naturally say.	3 / 3
Distinctiveness Conflict Risk	Occupies a clear niche as a repository auditing/mapping skill distinct from code generation, testing, or documentation skills. The specific triggers like 'harnessability score', 'fotografia do repo', and 'current.md' are highly distinctive and unlikely to conflict with other skills.	3 / 3
	Total	12 / 12 Passed

Validation

81%

Warnings & errors only

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: 9e5d744

Reviewed: 12 days ago

Table of Contents

Discovery Implementation Validation

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.