How do I install the Clarity Linter skill?

Run npx skillmds add majiayu000/clarity-linter in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Clarity Linter safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Clarity Linter?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Clarity Linter free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Clarity Linter?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Clarity Linter by majiayu000 — Agent Skill

Name: Clarity Linter
Rating: 4.2 (5 reviews)
Author: majiayu000

File contents

L1 Improvement

Rewrote the clarity linter as an English-first SOP with Prompt Architect-style constraint surfacing.
Added structure-first guardrails, adversarial validation hooks, and confidence ceilings per Skill Forge.
Consolidated input/output contracts into a single execution path for faster dogfooding.

STANDARD OPERATING PROCEDURE

Purpose

Assess readability and cognitive load, then deliver fixes with rubric-backed evidence.

Trigger Conditions

Positive: "clarity audit", "reduce cognitive load", "naming/readability review", "thin helper detection".
Negative: coupling-only analysis (use connascence-analyzer), security/performance scans, or quick lint (use quick-quality-check).

Guardrails

Structure-first package: SKILL.md, README.md, examples/, tests/, references/ kept current.
Use explicit clarity rubric (size, indirection, call depth, duplication, explanation quality) and cite evidence.
Apply confidence ceilings; do not overclaim automated fixes without human review when confidence <0.80.
Store runs in memory with WHO/WHY/WHEN/PROJECT tags for traceability.

Execution Phases

Intent & Scope – Confirm language, repo area, and goal (audit vs fix). Load domain expertise if available.
Metrics Collection – Gather size, nesting, call depth, duplication, naming signals, and comment density.
Rubric Evaluation – Score five dimensions; classify verdict (ACCEPT ≥0.80, REFINE 0.60–0.79, REJECT <0.60).
Fix Planning – Rank violations by impact; propose minimal-change patches.
Fix Generation – Apply or draft patches; keep diffs small and reversible.
Validation – Rerun metrics; ensure clarity score improves and tests still pass.
Delivery – Summarize findings, decisions, diffs, and confidence ceiling.

Input Contract (minimum)

target: file|directory with path.
policy: strict|standard|lenient (defaults to standard thresholds).
Flags: auto_fix (default false), report_format (md|json), min_score_threshold (default 0.60).

Output Format

Metrics snapshot, rubric scores, verdict, and top violations with evidence.
Fix plan and applied/queued patches.
Risks, follow-ups, and memory keys used.
Confidence: X.XX (ceiling: TYPE Y.YY).

Validation Checklist

Trigger confirmed; correct domain expertise loaded.
Rubric applied; evidence attached for each violation.
If auto-fix enabled, regressions and tests rerun.
Memory tagged and report stored.
Confidence ceiling declared.

Integration

Memory MCP: skills/tooling/clarity-linter/{project}/{timestamp} for reports and diffs.
Hooks: keep evaluation under post_hook_max_ms:1000; fail fast if metrics worsen.

Confidence: 0.70 (ceiling: inference 0.70) – SOP aligned to Prompt Architect constraint extraction and Skill Forge structure-first delivery.

---name: clarity-linterdescription: Evaluate and improve code clarity and cognitive load with rubric-driven scoring and targeted fixes.--- ### L1 Improvement - Rewrote the clarity linter as an English-first SOP with Prompt Architect-style constraint surfacing. - Added structure-first guardrails, adversarial validation hooks, and confidence ceilings per Skill Forge. - Consolidated input/output contracts into a single execution path for faster dogfooding. ## STANDARD OPERATING PROCEDURE ### Purpose Assess readability and cognitive load, then deliver fixes with rubric-backed evidence. ### Trigger Conditions - **Positive:** "clarity audit", "reduce cognitive load", "naming/readability review", "thin helper detection". - **Negative:** coupling-only analysis (use connascence-analyzer), security/performance scans, or quick lint (use quick-quality-check). ### Guardrails - Structure-first package: `SKILL.md`, `README.md`, `examples/`, `tests/`, `references/` kept current. - Use explicit clarity rubric (size, indirection, call depth, duplication, explanation quality) and cite evidence. - Apply confidence ceilings; do not overclaim automated fixes without human review when confidence <0.80. - Store runs in memory with WHO/WHY/WHEN/PROJECT tags for traceability. ### Execution Phases 1. **Intent & Scope** – Confirm language, repo area, and goal (audit vs fix). Load domain expertise if available. 2. **Metrics Collection** – Gather size, nesting, call depth, duplication, naming signals, and comment density. 3. **Rubric Evaluation** – Score five dimensions; classify verdict (ACCEPT ≥0.80, REFINE 0.60–0.79, REJECT <0.60). 4. **Fix Planning** – Rank violations by impact; propose minimal-change patches. 5. **Fix Generation** – Apply or draft patches; keep diffs small and reversible. 6. **Validation** – Rerun metrics; ensure clarity score improves and tests still pass. 7. **Delivery** – Summarize findings, decisions, diffs, and confidence ceiling. ### Input Contract (minimum) - `target`: file|directory with path. - `policy`: strict|standard|lenient (defaults to standard thresholds). - Flags: `auto_fix` (default false), `report_format` (md|json), `min_score_threshold` (default 0.60). ### Output Format - Metrics snapshot, rubric scores, verdict, and top violations with evidence. - Fix plan and applied/queued patches. - Risks, follow-ups, and memory keys used. - Confidence: X.XX (ceiling: TYPE Y.YY). ### Validation Checklist - [ ] Trigger confirmed; correct domain expertise loaded. - [ ] Rubric applied; evidence attached for each violation. - [ ] If auto-fix enabled, regressions and tests rerun. - [ ] Memory tagged and report stored. - [ ] Confidence ceiling declared. ### Integration - **Memory MCP:** `skills/tooling/clarity-linter/{project}/{timestamp}` for reports and diffs. - **Hooks:** keep evaluation under `post_hook_max_ms:1000`; fail fast if metrics worsen. Confidence: 0.70 (ceiling: inference 0.70) – SOP aligned to Prompt Architect constraint extraction and Skill Forge structure-first delivery.

Frequently asked questions