CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

beautify-github-readme

Redesign GitHub README homepages or create project-native pure SVG, hybrid SVG-composed PNG/WebP, and opt-in animated GIF assets. Use when a user asks to beautify, redesign, rebrand, visually upgrade, simplify, or audit a GitHub README; create only a hero, section headers, diagrams, badges, motion graphics, showcase modules, or other README assets; or turn a repository homepage into a cohesive visual story. If whole-README work versus asset-only work is unclear, ask which scope the user wants. For hero-like assets where pure SVG and generated raster material are both viable, explain the tradeoffs and confirm the implementation before creating the asset.

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-structured, highly actionable instruction skill with excellent progressive disclosure — a 10-step gated workflow, verbatim question scripts, concrete numeric production constraints, and a real, verified reference bundle. Its main costs are redundant restatement of the same safety policies across many sections and an implicit rather than explicit fix-and-re-validate loop around the audit step.

Suggestions

Consolidate repeated policies: state the GIF opt-in rule, the no-unauthorized-README-edit rule, and the attribution/showcase gate once each in an authoritative section, and reference that section elsewhere instead of restating full sentences in sections 1, 2, 6, 7, 8, 9, 10, and the Quality bar.

Add an explicit error-recovery loop to step 8: after "python3 scripts/audit_readme.py", instruct to review the reported issues, fix them, and re-run the audit until it passes before handing off.

Trim section 9's offer script and gating rules, which overlap heavily with the Quality bar's final bullet ("Optional attribution or showcase sharing appears only after explicit satisfaction and opt-in"); keep the quoted offer once and compress the surrounding rules to the single binding constraint.

DimensionReasoningScore

Conciseness

The body is dense and free of concept-explanation padding (no "what is SVG" material), but key policies are restated many times: the GIF opt-in rule appears in sections 1, 6, 7 and 8 ("GIF is opt-in and never the default", "Do not generate the GIF unless the user opted in"), the no-unauthorized-README-edit rule in sections 1, 2, 6, 8, 9, 10 and the Quality bar, and attribution gating in sections 7, 9 and the Quality bar. This matches the score-3 anchor ("mostly efficient but ... could be tightened") rather than 4, where over-explanation would be only minor — here whole sentences could be deleted by consolidating each policy into one authoritative location.

3 / 5

Actionability

Guidance is fully concrete: exact user-facing questions are quoted verbatim, the audit command is copy-paste ready ("python3 scripts/audit_readme.py /path/to/repository/README.md"), numeric constraints are specific ("1200-unit-wide SVG viewBox", "conservative 900 CSS-pixel GitHub render", "essential diagram text at least 20 SVG units"), and fill-in templates are given for the story extraction and art-direction spec. Matches the score-5 anchor — specific, executable guidance covering the common cases; per the rubric's scoring notes, absence of code in an instruction-only skill is not penalized when guidance is this actionable.

5 / 5

Workflow Clarity

Ten clearly sequenced steps with strong checkpoints: mode confirmation before editing ("Confirm the mode before editing"), implementation confirmation before hero-like assets, an explicit verification step ("Render a local GitHub-width preview", "Check wide and narrow layouts, image legibility, clipped SVG text ... dark/light-mode contrast"), and a safe hand-off. Falls short of the score-5 anchor because the error-recovery feedback loop is implicit — the audit script is run but the content never states what to do when it fails (fix and re-validate), unlike the anchor's "If errors: fix and re-validate" pattern, leaving a minor validation gap (score-4 anchor).

4 / 5

Progressive Disclosure

The body is a genuine overview that defers detail to eight well-signaled, task-timed references — "Read references/visual-direction.md" before freezing the theme, "read references/project-native-hero.md" before the hero, "read references/motion-production.md" for approved GIFs, "references/hybrid-svg-production.md" for hybrid composition — plus two bundled scripts; all referenced files exist and no reference nests another reference (one level deep). This is the score-5 anchor: clear overview, appropriately split content, easy navigation.

5 / 5

Total

17

/

20

Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is a strong example: comprehensive third-person capability statements, an explicit multi-trigger "Use when" clause, and tight scoping to GitHub README work that minimizes conflict with other skills. The only weakness is a few missing natural synonyms (banner, logo, README.md) that keep trigger coverage just short of comprehensive.

DimensionReasoningScore

Specificity

"Redesign GitHub README homepages", "create project-native pure SVG, hybrid SVG-composed PNG/WebP, and opt-in animated GIF assets" and the asset list "hero, section headers, diagrams, badges, motion graphics, showcase modules" name multiple concrete, comprehensive actions in third person ("Redesign", "create"). Matches the score-5 anchor (multiple specific concrete actions, comprehensive coverage) rather than 4, since coverage spans both whole-README and per-asset work with no meaningful gaps.

5 / 5

Completeness

Explicitly answers both questions: "what" via "Redesign GitHub README homepages or create ... pure SVG, hybrid SVG-composed PNG/WebP, and opt-in animated GIF assets", and "when" via the concrete "Use when a user asks to beautify, redesign, rebrand, ... or turn a repository homepage into a cohesive visual story" clause with trigger phrases. This is the score-5 anchor pattern (clear what AND when with concrete triggers), not 4, since the when-clause enumerates specific user requests rather than being merely adequate.

5 / 5

Trigger Term Quality

Strong natural coverage: "beautify, redesign, rebrand, visually upgrade, simplify, or audit", "hero, section headers, diagrams, badges, motion graphics", and "repository homepage" — all phrasings users would actually say. Falls short of the score-5 anchor because common synonyms like "banner", "logo", "illustration", and the file form "README.md" are absent, leaving a few natural terms missing (score-4 anchor).

4 / 5

Distinctiveness Conflict Risk

A clear niche (GitHub README visual work) with distinct triggers — every capability is scoped to "GitHub README" / "repository homepage" / "README assets", so it would not fire for general image-generation, charting, or document skills. Matches the score-5 anchor (clear niche, distinct triggers, minimal conflict risk); score 4 would require actual overlap with a closely related skill, which the consistent README scoping prevents.

5 / 5

Total

19

/

20

Passed

Validation

93%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

referenced_paths_exist

Referenced path issues: 1 possibly missing (assets/readme/)

Warning

Total

15

/

16

Passed

Repository

oil-oil/beautify-github-readme

Path

skills/beautify-github-readme/SKILL.md

Reviewed

Table of Contents

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.