agentleFS
TsukiNi22TsukiNi22/ai-utils/skills/audit/audit-quality/SKILL.md

audit-quality

Skill1 starsChanged 3 days agoMITView on GitHub

Audit the cleanliness and conventions of a project (the user's coding style, comments, file layout, CMake, git history, tests coverage, docs, hygiene) and deliver the result as a PDF report in the user's report style. Use whenever the user asks for an audit of cleanliness / quality / conventions / style / code hygiene, a "rapport de propreté", or a review of a whole project against his conventions (not for bugs/UB: audit-bugs).

2 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never start subagents (forks) by yourself: propose them only for very big projects and wait for the user's yes.

    line 19
  2. Very specific:

    When xstyle is installed (command -v xstyle, packages of TsukiNi22/xstyle), also run xstyle --rtk -r <root> -S -o /tmp/xstyle.json (the …

    line 32
  3. Very specific:

    Write the Markdown from report/templates/report.md, sections:

    line 62

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Cleanliness / convention audit -> PDF report

<name> (a skill) = the folder of that skill: ~/.claude/skills/<name> (setup.sh) or ${CLAUDE_SKILL_DIR}/../../*/<name> (plugin of the marketplace).

Report only: never modify the project during the audit (fixes only if asked afterwards). SKILL_DIR = directory of this file.

1. Ask (one AskUserQuestion call, French) - only what the request doesn't say

  • Scope: whole project / a module / the changes since a ref.
  • Compiler warnings pass (--build, slower: separate build dir in /tmp).
  • Output: ask the output format of report (Markdown + PDF recommended, PDF only, Markdown only); location audit/ at the root of the repository (or of the current folder outside a repository), never docs/ unless asked (audit/<YYYY-MM-DD>-quality.{md,pdf}); language English unless asked. Never start subagents (forks) by yourself: propose them only for very big projects and wait for the user's yes.

2. Objective metrics

python3 SKILL_DIR/scripts/collect.py <root> --json /tmp/audit.json --md /tmp/audit-tables.md [--build]

Categories (every finding has file:line): headers (Xartania/Epitech header missing), guards (NAME_H not matching the file), auto (outside iterators / structured bindings / lambdas), using-namespace, void-params (function with a return type and ()), c-cast, null, tabs, trailing-spaces, todo, cmake (source not listed, GLOB), gitignore (outputs not ignored), commits (not type(scope): message), ai-attribution, untested (public names never referenced by the tests, via cpp-tests), docs (README/CHANGELOG/LICENSE missing, CHANGELOG version != CMake version), warnings (with --build). The script is heuristic: check a sample of each category before reporting it, drop the false positives. When xstyle is installed (command -v xstyle, packages of TsukiNi22/xstyle), also run xstyle --rtk -r <root> -S -o /tmp/xstyle.json (the JSON for the counters, xstyle --rtk -r <root> to read the issues): ~65 rules of cpp-style / cpp-comments / coding-style / libutils usage with a severity (unforgivable / major / minor / negligible) and the counters by rule; use its counters in the report (sample-check them as well) and point to xstyle --fix [CODES] for the fixable ones (the command given to the user, who reads the human output; the assistant itself always runs xstyle with --rtk).

2b. Dependencies (licenses + vulnerabilities, transitive)

python3 <audit-deps>/scripts/deps.py <root> --transitive --json /tmp/deps.json --md /tmp/deps.md
python3 <audit-deps>/scripts/vulns.py <root> --json /tmp/vulns.json --md /tmp/vulns.md

Licenses to credit / restrictive / unknown (see audit-deps), known vulnerabilities and compromised versions (OSV, dnf advisories, GitHub advisories), recent ones (< 90 days) first; for each one check whether the project uses the vulnerable part. Dependencies of the dependencies are included.

3. Manual review (what a script can't see)

Load the convention skills and read a representative sample of each module (most recent files first):

  • cpp-style (naming, braces, this->, one-liners, const, alignment), cpp-comments / comments, cpp-class (reference/layout.md: sections, class blocks order, rule of five, include comments, namespaces),
  • cmake-style (section order, banners, modes, packaging), git-conventions (history, tags, CHANGELOG),
  • readme-style / html-doc (docs), cpp-tests (tests structure), license (scripts/license.py identify). Also: dead code, duplicated code, very long functions, magic numbers, inconsistent naming between modules, files in the wrong folder, leftovers at the root (tmp.cpp, a.out...).

4. Score and priorities

Per category: number of findings, severity (high: breaks the build/CI/conventions everywhere, medium: recurrent deviation, low: cosmetic), a 0-10 score, the fix (and if it can be automated: sed, script, clang-format...). Then a top 10 of the actions with the best gain / effort ratio.

5. Report (report skill)

Write the Markdown from report/templates/report.md, sections:

  1. Summary: table | Category | Findings | Severity | Score /10 | + global score + 3-line verdict.
  2. Method: scope, commit (git rev-parse --short HEAD), date, tools and skills used, limits (heuristics).
  3. Findings by category: one ### per category, a short explanation of the rule (with the skill it comes from), a table | File:line | Finding | Fix | (max ~15 rows, the rest in the annex).
  4. Dependencies: licenses (table + obligations) and vulnerabilities (table by severity, recent first, fixed version, action).
  5. Priorities: the top 10, numbered 1. **Action.** gain, effort, files.
  6. Appendix: full lists per category (from the JSON), module sizes table.
  7. Sources: the skills / rules / tools used. Then python3 <report>/scripts/md2pdf.py <report.md> --footer "<Project> — quality audit" --format <answer>, check the rendering (pdftoppm on 2 pages) and give both paths + page count.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.