Fix punctuation and grammar in skill reference docs#135
Conversation
Follow-up to #134, which scoped validateProse to user-facing copy and left the LLM-facing skill files alone. Bring those to the same bar, phased so hardening repetition stays intact. - Em dashes: 419 → 0 across SKILL.md and 35 reference files. Each replacement picks the right relationship (colon, semicolon, period, or parens) instead of letting the dash hide the choice. - Closer cleanup: deleted or rewrote the "Remember:" sermonettes that were pure adjective chants (bolder/quieter/clarify/delight/extract/ colorize/layout/typeset/audit/adapt). Survivors that load-bear an instruction now hand off to /impeccable polish instead of summarizing. - Opener taglines: rewrote the "[Verb] [object] to [outcome]" brochure openers in 12 older files to lead with the failure mode, the strongest claim, or a directive. Newer files (live, brand, product, audit, critique, harden) kept their existing openers. - data-driven: rephrased the two technical hits in live.md so the validator can stay strict on this term. - validateSkillProse: narrow validator scoped to source/skills/impeccable/. Em-dash check + the small denylist of phrases with no technical reading. Hardening repetition and structural-prose rules are deliberately not enforced — those need human judgment. Test failure on detectUrl is pre-existing (puppeteer needs --no-sandbox when running as root); unrelated to these changes. https://claude.ai/code/session_013zZY6rbB1bS8z3D63rX5hW
🔍 Tessl Skill Review
|
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ██░ 2/3 | The skill is fairly dense and information-rich, but includes some unnecessary explanation (e.g., the extended color strategy descriptions, the physical scene exercise for theme selection, and the AI slop test section are verbose). However, most content is domain-specific knowledge Claude wouldn't inherently have, so it earns its place more often than not. |
| actionability | ███ 3/3 | Highly actionable throughout: concrete bash commands for context loading and pinning, a precise preflight checklist with pass/fail gates, specific CSS rules (OKLCH, no #000/#fff, chroma ranges), exact thresholds (65-75ch line length, ≥1.25 ratio), and a clear command routing table with file references. The absolute bans are specific enough to be match-and-refuse patterns. |
| workflow clarity | ███ 3/3 | The setup section is an exemplary gated workflow with a clear table of prerequisites, explicit pass/fail conditions, and a mutation gate that prevents file edits until all checks pass. The preflight string format provides a concrete validation checkpoint. The routing rules clearly sequence how commands are dispatched, and the context-gathering flow has explicit fallback paths and re-run conditions. |
| progressive disclosure | ███ 3/3 | Excellent progressive disclosure: the main SKILL.md provides shared laws and setup, then delegates each of 25+ commands to individual reference files with clear one-level-deep links (e.g., [reference/craft.md]). The command table serves as a navigation hub. Register-specific content is split into brand.md and product.md references. No deeply nested chains. |
Overall: This is a sophisticated, well-architected skill with exceptional workflow clarity and progressive disclosure. The gated preflight system, absolute bans, and command routing are highly actionable and precisely specified. The main weakness is moderate verbosity in the design laws section—some explanatory passages (the scene-sentence exercise, the two-altitude reflex check) could be tightened without losing meaning, though much of this content represents genuinely novel design guidance Claude wouldn't otherwise know.
.claude/skills/impeccable/SKILL.md
⚠️ Error: - Reviewing skill...
✘ Skill validation failed
.cursor/skills/impeccable/SKILL.md
Review Details
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ██░ 2/3 | The skill is dense and information-rich, with most content earning its place (design laws, absolute bans, color strategies). However, some sections over-explain concepts Claude would understand (e.g., the extended theme-choosing rationale with the 'write one sentence of physical scene' walkthrough) and the setup gates section is somewhat verbose with its table + prose + preflight string format. |
| actionability | ███ 3/3 | Highly actionable throughout: concrete bash commands for context loading and pinning, specific CSS property bans with alternatives, exact OKLCH chroma ranges, precise line-length caps, named easing curves, a structured preflight checklist with pass/fail conditions, and clear routing rules. The skill tells Claude exactly what to do and what not to do. |
| workflow clarity | ███ 3/3 | The setup gates table provides an explicit sequenced checklist with clear pass/fail conditions and remediation steps for each gate. The preflight string acts as a validation checkpoint before any mutation. The routing rules clearly sequence how commands are dispatched, and the context-gathering flow has explicit conditional logic (if missing → run teach → refresh → resume). |
| progressive disclosure | ███ 3/3 | Excellent progressive disclosure: the main SKILL.md provides shared design laws and setup, then cleanly delegates each of 25+ commands to individual reference files with clear relative paths. References are consistently one level deep (SKILL.md → reference/*.md). The command table serves as a navigable index with descriptions and direct links. |
Overall: This is a sophisticated, well-architected skill that demonstrates excellent progressive disclosure through its command-reference structure and strong workflow clarity through its gated preflight system. The design laws are opinionated and actionable with specific values and concrete bans. Minor verbosity in the setup and theme sections prevents a perfect conciseness score, but overall the content is high quality and well-suited for guiding Claude through complex frontend design tasks.
.gemini/skills/impeccable/SKILL.md
Review Details
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ██░ 2/3 | The skill is fairly dense and information-rich, but includes some unnecessary verbosity—e.g., the extended color strategy explanations, the physical scene exercise for theme selection, and the AI slop test section with multi-paragraph reflex checks. Some of this is genuinely novel instruction Claude wouldn't know, but the design laws section could be tightened significantly. |
| actionability | ███ 3/3 | The skill provides highly concrete, actionable guidance: exact bash commands for context loading and pinning, a precise preflight checklist with pass/fail gates, specific CSS rules (OKLCH, no #000/#fff, no border-left accents), exact thresholds (65-75ch line length, ≥1.25 ratio), and a clear routing algorithm. The absolute bans are specific and match-and-refuse actionable. |
| workflow clarity | ███ 3/3 | The setup section is an exemplary gated workflow with a clear table of gates, required checks, and failure actions. The preflight string format provides an explicit validation checkpoint. The routing rules are clearly sequenced (no argument → table, first word matches → load reference, else → general invocation). The mutation gate prevents file edits until all checks pass, which is a strong feedback loop for destructive operations. |
| progressive disclosure | ███ 3/3 | The skill is structured as a clear overview with well-signaled one-level-deep references to 22+ command reference files (reference/craft.md, reference/shape.md, etc.) and two register references (reference/brand.md, reference/product.md). The main file contains shared laws and routing logic while delegating command-specific details to individual reference files. Navigation is clear via the command table with linked references. |
Overall: This is a sophisticated, well-architected skill with excellent workflow clarity through its gated preflight system and strong progressive disclosure via its command reference structure. The actionability is outstanding with specific, concrete rules and executable commands. The main weakness is moderate verbosity in the design laws section—some passages (the AI slop test, color strategy axis, theme scene-sentence exercise) could be tightened without losing meaning, though much of this content is genuinely novel instruction that Claude wouldn't have by default.
.github/skills/impeccable/SKILL.md
Review Details
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ██░ 2/3 | The skill is fairly dense and information-rich, but includes some unnecessary explanation (e.g., the physical scene exercise for theme selection is verbose, and some design law rationales could be tighter). However, most content earns its place as domain-specific guidance Claude wouldn't inherently know. |
| actionability | ███ 3/3 | Highly actionable: concrete bash commands for context loading and pinning, a precise preflight checklist with pass/fail gates, specific CSS rules (OKLCH, no #000/#fff, chroma ranges), explicit absolute bans with alternatives, and clear routing rules. The guidance is specific and directly executable. |
| workflow clarity | ███ 3/3 | The setup gates table provides an explicit sequenced workflow with clear pass/fail conditions and remediation steps for each gate. The preflight string acts as a validation checkpoint. The routing rules clearly sequence how commands are dispatched. The mutation gate prevents file edits until all checks pass, serving as a critical validation checkpoint. |
| progressive disclosure | ███ 3/3 | Excellent progressive disclosure: the SKILL.md serves as a clear overview with shared laws and setup, while each of the 24+ commands references a dedicated file (e.g., reference/craft.md, reference/shape.md). References are one level deep, clearly signaled in a well-organized table, and the content appropriately splits shared concerns from command-specific details. |
Overall: This is a sophisticated, well-structured skill that provides highly actionable design guidance with clear workflows and excellent progressive disclosure across many sub-commands. The preflight gate system is a strong validation mechanism that prevents premature file mutations. Minor verbosity in some design law sections (theme scene exercise, color strategy descriptions) could be tightened, but most content represents genuinely novel domain knowledge that Claude needs.
.kiro/skills/impeccable/SKILL.md
Review Details
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ██░ 2/3 | The skill is fairly dense and information-rich, but includes some unnecessary verbosity—e.g., the extended color strategy explanations, the physical scene exercise for theme selection, and the AI slop test section with its multi-paragraph reflex checks. Some of this is genuinely novel guidance Claude wouldn't know, but the prose could be tightened significantly. |
| actionability | ███ 3/3 | The skill provides highly concrete, actionable guidance: specific bash commands for context loading and pinning, a precise preflight checklist with pass/fail gates, exact CSS rules to ban, specific OKLCH color guidance with numeric ranges, and a clear routing algorithm for command dispatch. The instructions are executable and specific. |
| workflow clarity | ███ 3/3 | The setup section defines a rigorous gate-based workflow with explicit pass/fail conditions and remediation steps for each gate. The preflight checklist is a clear validation checkpoint before any mutation. The routing rules provide unambiguous sequencing for command handling, and the context-gathering flow has explicit conditional logic for missing files. |
| progressive disclosure | ███ 3/3 | The skill is an excellent overview that delegates to 20+ reference files (reference/craft.md, reference/shape.md, etc.) via clearly signaled one-level-deep links. The command table provides a navigable index. Shared laws are inline (appropriately, as they apply universally), while register-specific and command-specific details are properly externalized. |
Overall: This is a sophisticated, well-architected skill with exceptional workflow clarity and progressive disclosure. The gate-based preflight system, absolute bans, and routing rules are highly actionable and concrete. The main weakness is moderate verbosity in the design laws section—the AI slop test, color strategy descriptions, and theme selection exercise could be more concise without losing their novel value.
Suggestions:
- Tighten the 'AI slop test' section: the first-order/second-order reflex check explanation is verbose and could be condensed to a compact checklist format.
- Compress the color strategy descriptions—the four-step commitment axis could be a compact table rather than prose with inline commentary.
.opencode/skills/impeccable/SKILL.md
⚠️ Error: - Reviewing skill...
✘ Skill validation failed
.pi/skills/impeccable/SKILL.md
⚠️ Error: - Reviewing skill...
✘ Skill validation failed
.qoder/skills/impeccable/SKILL.md
⚠️ Error: - Reviewing skill...
✘ Skill validation failed
.rovodev/skills/impeccable/SKILL.md
⚠️ Error: - Reviewing skill...
✘ Skill validation failed
.trae-cn/skills/impeccable/SKILL.md
Review Details
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ██░ 2/3 | The skill is fairly dense and information-rich, but includes some unnecessary verbosity—e.g., the extended color strategy explanations, the physical scene exercise for theme selection, and the AI slop test section with multi-paragraph reflex checks. Some of this is genuinely novel guidance Claude wouldn't know, but the prose could be tightened significantly. |
| actionability | ███ 3/3 | The skill provides highly concrete, actionable guidance: specific bash commands for context loading and pinning, a clear preflight checklist with exact pass/fail conditions, explicit routing rules, absolute bans with specific CSS properties named, and a structured gate table with fallback actions. The guidance is precise and executable. |
| workflow clarity | ███ 3/3 | The setup gates are presented as a clear sequential checklist with explicit pass/fail conditions and remediation steps for each failure. The preflight string format provides a validation checkpoint before any mutation. The routing rules clearly sequence how commands are dispatched, and the craft flow explicitly chains through shape before implementation. |
| progressive disclosure | ███ 3/3 | The skill is an excellent overview that delegates to 20+ reference files (reference/craft.md, reference/shape.md, etc.) via clearly signaled one-level-deep links. The command table serves as a navigation hub, and detailed instructions for each sub-command live in their own files. The structure is well-organized with clear sections for setup, design laws, commands, and routing. |
Overall: This is a well-architected skill with exceptional workflow clarity and progressive disclosure. The setup gates, preflight checklist, and routing rules provide unambiguous operational guidance. The design laws section contains genuinely novel, opinionated guidance (OKLCH color strategy, absolute bans, AI slop test) that Claude wouldn't know by default, though some sections could be more concise—particularly the theme selection exercise and the two-tier reflex check explanation.
Suggestions:
- Tighten the 'Theme' section—the physical scene exercise and examples could be condensed to 2-3 lines instead of the current paragraph-heavy format.
- The 'AI slop test' and 'Category-reflex check' sections are verbose for what they convey; consider condensing the first-order/second-order explanation into a compact checklist format.
.trae/skills/impeccable/SKILL.md
Review Details
Review Details
| Dimension | Score | Detail |
|---|---|---|
| conciseness | ██░ 2/3 | The skill is dense and information-rich, but some sections are more verbose than necessary. The 'Shared design laws' section is well-written and earns its tokens with specific, actionable rules. However, the setup gates section has some redundancy (e.g., explaining the same PRODUCT.md validation multiple times), and the AI slop test explanation could be tighter. Overall mostly efficient but not maximally lean. |
| actionability | ███ 3/3 | Highly actionable throughout. The setup gates table provides exact checks and failure actions. Concrete commands are given (e.g., node .trae/skills/impeccable/scripts/load-context.mjs), the preflight string format is copy-paste ready, design laws give specific values (OKLCH, chroma 0.005–0.01, 65–75ch line length, ≥1.25 ratio), and absolute bans name exact CSS properties to avoid. The pin/unpin commands are fully executable. |
| workflow clarity | ███ 3/3 | The setup gates table is an excellent workflow with clear sequencing and explicit validation checkpoints (each gate has a required check and a failure action). The mutation gate acts as a final validation checkpoint preventing premature file edits. The routing rules provide clear decision logic. The preflight string serves as a verification checklist. The flow from context → register → design laws → command dispatch is well-sequenced. |
| progressive disclosure | ███ 3/3 | Exemplary progressive disclosure. The SKILL.md serves as a clear overview with shared laws and setup, while each of the 24+ commands references a dedicated file (e.g., reference/craft.md, reference/brand.md). References are one level deep, clearly signaled in a well-organized table, and the routing rules explain exactly when to load each reference. The register-specific content is appropriately split into reference/brand.md and reference/product.md. |
Overall: This is a sophisticated, well-structured skill that demonstrates excellent craft in its own right. The setup gates with explicit validation checkpoints, the concrete design laws with specific values and absolute bans, and the clean progressive disclosure into 24+ command references make this highly actionable and well-organized. Minor verbosity in some explanatory sections (AI slop test, second-order reflex check) prevents a perfect conciseness score, but the content density is generally justified by the complexity of the domain.
plugin/skills/impeccable/SKILL.md
⚠️ Error: - Reviewing skill...
✘ Skill validation failed
source/skills/impeccable/SKILL.md
⚠️ Error: - Reviewing skill...
✘ Skill validation failed
To improve your score, point your agent at the Tessl optimization guide. Need help? Jump on our Discord.
Feedback
Report issues with this review at tesslio/skill-review, or send private feedback from your terminal with tessl feedback.
2 participants
Summary
This PR corrects punctuation and grammar inconsistencies across skill reference documentation files. The changes standardize formatting for improved readability and consistency:
—) with colons (:) or semicolons (;) in numbered lists and explanatory text.agents/,.claude/,.cursor/,.gemini/,.github/)Type of change
Details
Changes affect the following reference files across multiple provider directories:
live.md- Fixed em dashes in numbered list itemsheuristics-scoring.md- Standardized punctuation in introductory textdocument.md- Minor formatting adjustmentslayout.md,overdrive.md- Opening sentence refinementsAll changes are purely stylistic and improve documentation clarity without altering technical content or guidance.
Checklist
bun run buildran successfully (documentation-only changes)bun testpasses (documentation-only changes)https://claude.ai/code/session_013zZY6rbB1bS8z3D63rX5hW
Note
Low Risk
Documentation-only edits across
impeccableskill references; no runtime or behavioral code changes, with minimal risk beyond potential meaning drift in guidance.Overview
Standardizes punctuation, list formatting, and sentence structure across the
impeccableskill docs (e.g., replacing em-dash phrasing with colons/semicolons, tightening bullets/numbered rules, and clarifying a few key directives).Several command references now end with consistent handoff guidance to
\$impeccable polish, improving consistency and readability without changing implementation code.Reviewed by Cursor Bugbot for commit 3edd693. Bugbot is set up for automated code reviews on this repo. Configure here.