Guide · Agent skill
How to use the Better Colors agent skill: install and examples
Updated · written with AI from the project's own documentation and checked against our catalogue data
Better Colors is an agent skill, a packaged set of instructions that an AI coding agent such as Claude loads when a task calls for it. It is built for front-end developers and designers who are setting up, cleaning up or migrating a color system. After this guide you will know what the skill changes about the agent's behaviour, how to install it, how to phrase requests so it triggers, and what to check before trusting its output.
Better Colorsjakubkrehel/skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the better-colors ZIP from the skill's page on this directory.
- 2Unzip into the skills folder. Extract it into ~/.claude/skills/ for a personal install, or into .claude/skills/ inside a project for a shared one.
- 3Or upload in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the ZIP.
- 4Describe a color task. Ask in plain language, mentioning palettes, tokens, contrast or conversion, and name the files involved.
- 5Review the findings. Read the report, which lists problems by severity with locations and the principle each one breaks.
- 6Approve changes explicitly. Ask the agent to change colors only for the findings you accept, then ask it to remeasure contrast.
What the better-colors skill makes the agent do
With the skill installed, the agent builds and audits color systems with a fixed set of rules. It generates color ramps, which are light-to-dark steps of one hue, and maps each step to a job such as page background, border, solid fill or body text. It names design tokens by role rather than by color, for example --color-text-secondary instead of --color-blue-600 in a component, converts between color notations and measures contrast between text and the background it actually renders on.
The skill also tells the agent how to report. It flags problems such as a token used in the wrong role or a failing contrast pair, and it leaves colors unchanged unless you ask for a change. Pass or fail requirements for contrast are handled by a separate skill, better-accessibility.
- Generates ramps and maps steps to roles
- Names primitive and semantic tokens
- Converts between color formats such as hex and OKLCH
- Measures contrast of a foreground against its real background
- Reports findings by severity without changing colors unasked
Install the better-colors skill
The skill ships as a ZIP file from the skill's page on this directory. Download it and unzip it into one of two locations. For a personal install available in every project, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so it is shared with everyone who works in that repository.
If you use the Claude apps instead of a local setup, you can upload the ZIP in the app under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Check the skill files after installing
The package contains a SKILL.md file, which holds the instructions the agent reads, plus supporting reference files: color-formats.md, color-usage.md, contrast.md, palette-generation.md, palette-structure.md and token-naming.md. An agents/openai.yaml file is also included. Keep the folder structure intact so the agent can open the reference files when a task needs them.
- SKILL.md: the main instructions
- color-formats.md: notations and conversion
- palette-generation.md and palette-structure.md: ramps and step roles
- token-naming.md: naming semantic tokens
- contrast.md and color-usage.md: measuring pairs and applying colors
How to trigger the skill with natural requests
You do not need a special command. Describe the color task in plain language and mention colors, palettes, tokens, contrast or conversion so the agent matches the skill to your request. Name the project's files when you can, because the skill reuses the project's existing tokens and notation rather than imposing its own.
Be explicit when you want a change made. By default the skill reports problems and leaves colors alone.
- Ask for a full palette: build an accent ramp for our brand color and map steps to background, border and text roles.
- Ask for an audit: review the color tokens in src/styles for role misuse and naming problems.
- Ask for a conversion: convert our hex tokens to OKLCH and keep the same visual result.
- Ask for a contrast measurement: measure the text on the card background in both light and dark themes.
- Ask for changes explicitly: fix the failing contrast pair by changing lightness.
What the skill needs and what it does not do
The skill lists no required tools. It does not run scripts and does not use the network. Without a browser, the agent can only check declared token values, the color gamut of declared colors and contrast computed from the declared token pair. It cannot see how a page actually looks.
Because it works from declared values, a contrast result without a rendered check is limited. The skill asks the agent to list any check it could not run as Not verified.
- No listed requirements
- No scripts run
- No network use
- Without a browser, visual appearance is not verified
Safety notes on scripts and network access
The skill is documented as running no scripts and making no network requests, so installing it does not add executable code or outbound connections. Its effect comes from instructions the agent follows while it reads and edits your files. Review the SKILL.md file before installing if you want to see exactly what rules the agent will apply. The skill is licensed under MIT.
- Runs scripts: no
- Uses network: no
- Licence: MIT
- Review SKILL.md to see every rule before installing
Tips for getting useful results
Give the agent your existing notation and token names so it keeps them. The skill prefers the project's own format, and it recommends OKLCH only for a genuinely new system. Ask for a single accent ramp first; the skill's guidance is that extra hues should earn their place. Treat contrast values as measurements of declared colors, and remeasure after any change.
- Share your current token file so the agent reuses it
- Start with one accent ramp instead of several hues
- Ask for findings first, then approve the changes you want
- Confirm that anything marked Not verified is checked by you in a browser
What people use it for
- Building a light-to-dark accent ramp and mapping its steps to background, border and text roles
- Renaming color tokens from hue names such as --color-blue-button to role names such as --color-accent-solid
- Converting a hex color codebase to OKLCH while keeping the same look
- Measuring text contrast on a card background in light and dark themes
- Auditing a stylesheet for a token used outside its role, such as a border color used as text
Frequently asked questions
How do I install the better-colors skill?
Download the ZIP from the skill's page, then unzip it into ~/.claude/skills/ for a personal install or into a project's .claude/skills/ folder for a shared one. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.
What does the better-colors skill require?
The skill lists no required tools. It runs no scripts and uses no network. It works from declared token values and computed contrast, and it cannot verify visual appearance without a browser.
Is better-colors free to use?
The skill is licensed under MIT, as stated on its page. Check the license file in the package for the full terms.
Does better-colors check accessibility compliance?
Not on its own. Pass or fail requirements belong to the separate better-accessibility skill. Better-colors computes contrast values and reports them against the thresholds that apply.
Will the skill change my colors automatically?
No. When a pair fails or a role is misused, it reports the problem and leaves the colors unchanged unless you ask for a change.
Should I use this skill for a quick color pick?
Probably not. The skill adds process that is more than a quick color pick needs. It suits setting up, cleaning up or migrating a real color system.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Better Colors suits front-end developers and designers who maintain a real color system and want structure, consistent token names and measured contrast checked with discipline. It is less useful for a one-off color choice, for formal accessibility sign-off, or for anyone who needs the agent to judge how a page visually looks without a browser.
Download the skill