agentleFS
L-X-TL-X-T/ng-agentic-skills/.agents/skills/ng-review-style-guide/SKILL.md

ng-review-style-guide

Skill13 starsChanged 44 days agoMITView on GitHub

Audit the whole Angular codebase against the project style guide (all of style-guide/, auto-selected by file type) and report severity-ranked conformance findings, then drill in and fix on approval. Use when the user wants a full-codebase style-guide review, a conformance audit, to check the existing code against the style guide, or to find where the codebase drifted from the guide – as opposed to reviewing a diff (use code-review) or only SCSS/styling (use ng-styling).

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Default scope is the whole codebase (src/).

    line 38
  2. Very specific:

    Read style-guide/style-guide.md first – the baseline applies to everything.

    line 53
  3. Distinctive:

    Use configured static checks and deterministic searches before manual review.

    line 75
  4. Very specific:

    Run lint only when the project has a lint target.

    line 78
  5. Very specific:

    Search for likely guide violations with rg, then confirm or reject each hit against the loaded guide:

    line 83
  6. Very specific:

    Write the full report to reports/ng-review-style-guide/current.md so drift is tracked over time, then give a short chat summary …

    line 121
  7. Distinctive:

    Only after the user picks a finding.

    line 135
  8. Distinctive:

    After every batch run non-mutating verification and don't proceed until green:

    line 139
  9. Very specific:

    If a formatter or lint fixer is needed, run it only on the touched files after re-reading them.

    line 144
  10. Distinctive:

    Preserve meaning: Keep existing comments, documented workarounds, and user edits intact.

    line 161
  11. Distinctive:

    Git discipline: Never stage, commit, or push, and never start a dev server – surface the diff and let the user commit.

    line 164

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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

Review the codebase against the style guide

The other review skills are scoped to a slice of the work: code-review judges a diff (changed / staged / last-commit / PR), and ng-styling goes deep on SCSS / styling. This skill is the whole-codebase conformance sweep: how far has the code already in src/ drifted from the project's written style guide, across every relevant guide at once?

The style guide is the law here. The guides under style-guide/ are the sole source of truth – read them, judge against them, cite them. Do not invent rules from general Angular knowledge; if a rule isn't in the guide (or in AGENTS.md), it isn't a finding. AGENTS.md and the project guides override any generic example in this skill.

The audit is the default and is read-only. Fixing is opt-in, one finding at a time, after you approve it.

Severity (mirrors the style guide)

SeverityMeansMaps to
🔴 MustA violation – fix itthe guide's "Must do" / "Don't" and AGENTS.md hard rules
🟡 ShouldA strong recommendation – fix unless justifiedthe guide's "Should do"
🔵 AdvisoryAn opportunity to considersofter "prefer" / "consider" wording

Process

1. Scope & inventory

Default scope is the whole codebase (src/). Accept a narrower scope when the user names one (a path, a feature folder, a component). This is a plain Angular app (single angular.json, no nx.json); judge against feature folders, not buildable libraries.

Inventory which file types actually exist in scope, because that decides which guides load in step 2. Use a fast sweep, e.g.:

git ls-files src | sed 's/.*\.//' | sort | uniq -c

Done when the scope is fixed and every file type present is listed with a count.

2. Load the guides (auto-selected by file type)

Read style-guide/style-guide.md first – the baseline applies to everything. Then load only the specific guides for file types found in step 1, and record an explicit not-applicable note for the rest:

File type / signalGuide
.ts (components, services, logic)style-guide.ts.md
.html templatesstyle-guide.html.md
.scss / stylingstyle-guide.scss.md
templates / interactive UIstyle-guide.a11y.md
.spec.ts, e2e testsstyle-guide.spec.md
package.json, dependency filesstyle-guide.npm.md
.md documentationstyle-guide.md.md

Git workflow (style-guide.git.md) is about commits and branches, not files in the tree – skip it for a codebase audit unless the user asks.

Done when the baseline plus every applicable specific guide is loaded, and skipped guides are noted as not-applicable.

3. Run deterministic checks

Use configured static checks and deterministic searches before manual review. They are evidence, not the whole audit: every hit must be read in context before it becomes a finding.

Run lint only when the project has a lint target. Resolve commands from package.json / workspace config (pnpm lint or ng lint), and record pass/fail output. Do not run tests, builds, formatters, fixers, e2e checks, or dev servers during the read-only audit unless the user explicitly asks.

Search for likely guide violations with rg, then confirm or reject each hit against the loaded guide:

  • TypeScript / Angular: decorator APIs replaced by signal APIs, standalone: true, avoidable lifecycle hooks, @HostBinding / @HostListener, any, debug logging, direct NodeListOf / HTMLCollectionOf iteration, non-signal data-fetching patterns.
  • Templates / a11y: ngClass / ngStyle, structural directives, template function calls, missing button type, non-semantic click targets, ARIA or focus-management drift.
  • SCSS signals – see the ng-styling skill and style-guide.scss.md for the specific rules to search.
  • Tests / docs / packages: only when those file types are in scope, check against their loaded guide.

Done when lint results are recorded and every deterministic hit is confirmed, rejected, or downgraded to a signal with evidence.

4. Audit

Turn each loaded guide into concrete checks and sweep the scope against them. Drive detection with rg and targeted reads; for a large codebase, fan out read-only explorer subagents when available by area or file type so breadth doesn't blow the context – each returns its findings, you consolidate. Most guide rules are caught by reading and reasoning, not by a linter.

For every finding record: severity · guide (e.g. [ts] / [html] / [scss]) · file:line · the rule · what's wrong · suggested fix · fixable = mechanical | judgment.

Be honest about the bound: account for every file type in scope, not just the easy ones. A clean guide is a valid result – say "no findings against [spec]" rather than omitting it.

Done when every applicable guide has been swept across the full scope, deterministic signals are resolved, and findings are recorded in that shape (or the guide is recorded as clean).

5. Report

Render a grouped Markdown report. Group by guide; within each group lead with 🔴 Must, then 🟡 Should, then 🔵 Advisory. Open with a one-paragraph conformance summary (overall health, which guides are clean, where the drift concentrates) and close with per-severity counts and a suggested fix order.

Write the full report to reports/ng-review-style-guide/current.md so drift is tracked over time, then give a short chat summary (per-severity counts plus the report path). This artifact is the only write the audit makes – read the existing current.md first if it exists and overwrite just that file; touch no source, test, config, or other files while writing it. If the user would rather keep the report in chat only, skip the file.

End with: "Which finding would you like to fix?" Do not start fixing yet.

Done when the report is written to reports/ng-review-style-guide/current.md (or kept in chat by request), the chat summary carries the same per-severity counts, every finding cites its guide and file:line, no source files were touched, and the run has stopped for the user to choose.

6. Drill in & fix on approval

Only after the user picks a finding. Fix in small, verified, single-purpose batches – one coherent kind of change per batch – honoring AGENTS.md: minimal diffs, no opportunistic refactors, preserve existing comments and user edits, re-read each file immediately before editing.

After every batch run non-mutating verification and don't proceed until green:

build (pnpm build) → lint (pnpm lint or project lint) → format check on touched files (pnpm exec prettier --check <files>) → test (pnpm test --watch=false, only if behavior or templates changed)

If a formatter or lint fixer is needed, run it only on the touched files after re-reading them; never run repo-wide pnpm format or broad --fix commands during a skill fix batch. Read each diff top-to-bottom; every edit must move the code closer to the guide and earn its keep. Re-audit the touched scope so it shows clean. Then return to the report for the next finding.

Done when each chosen finding is fixed and verified, explicitly deferred, or rejected with evidence – and the working tree is left for the user to stage and commit.

Guardrails (non-negotiable)

  • Guide is the only law. Cite a guide for every finding. No guide rule, no finding – don't smuggle in general Angular opinions. Severity follows the guide's own Must/Should wording.
  • Audit first; fixing is opt-in. A run touches no source code until the user approves a specific fix. The audit's only write is the report artifact at reports/ng-review-style-guide/current.md.
  • No big-bang rewrite. Small, reviewable, single-purpose batches – never a sweeping codebase conformance edit.
  • Minimal diffs. Change only what the finding requires. No "while I'm here" cleanups (AGENTS.md).
  • Preserve meaning. Keep existing comments, documented workarounds, and user edits intact.
  • Treat the agent like a junior. "Done" means the diff was read by a human, not that the agent said so.
  • Git discipline. Never stage, commit, or push, and never start a dev server – surface the diff and let the user commit.

Pairs with

  • code-review – the diff-scoped counterpart; use it for changed/staged/ PR work, this skill for the standing codebase.
  • ng-styling – go here when the SCSS/styling findings warrant a deep, appearance-preserving fix pass against the three styling sources of truth.
  • ng-accessibility – deeper a11y remediation beyond the [a11y] guide checks.
  • ng-review-architecture – when drift is structural (domain boundaries, module depth) rather than per-file style.

Origin

Authored in this repository against Alexander Thalhammer's project style guide (style-guide/). MIT-licensed.

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.