A Claude design Skill can give an AI repeatable instructions for using your design system, but it cannot make brand rules reliable by itself. If a Skill says to use color.brand.primary and documented button variants, Claude still needs access to the token file, component inventory, or other relevant project context to apply those rules to a real settings page.
Use general aesthetic guidance when you want creative direction and no strict house system applies. Build a custom Skill when approved tokens, components, accessibility rules, and prohibited patterns must take priority. Then compare the result with the same task without the Skill, run machine-checkable validations, and have a person review the rendered outcome.
This guide treats a design Skill as versioned operating guidance. It explains what a Skill can control, how to choose between general direction and system-specific rules, how to package and deploy the Skill across surfaces, and how to evaluate it without turning one attractive screenshot into a performance claim.
What a Claude design Skill can and cannot control
A Claude Skill is a directory-based package centered on a SKILL.md file. Its YAML frontmatter must include name and description. References, assets, and executable scripts are optional. Claude uses the description to decide whether a Skill is relevant, then loads the instructions and linked resources as needed. This is progressive loading, not a universal fixed token charge for every installed Skill. See the Anthropic Agent Skills overview and the Agent Skills specification.
A Skill supplies instructions, not automatic access to your current product, repository, or Figma file. Make the necessary files available on the surface you are using, or configure a verified tool connection. Keep these roles distinct:
- Skill: repeatable instructions, design rules, and procedures.
- MCP: a connection that can provide access to an external tool, such as Figma, when configured and authorized.
- Claude Design: a canvas-oriented way to create and refine visual work. Claude Design is now integrated into Claude, and the standalone experience is documented as scheduled to close on December 14, 2026.
Claude Design and a custom SKILL.md are not interchangeable. An imported design system in Claude Design is not automatically the same thing as a Skill package.
A Skill can carry design rules. The design system remains the source of truth, and the task still needs the files or tool access required to apply those rules.
Choose the right starting point
Anthropic’s frontend-design plugin and Skill provide general aesthetic and implementation guidance for frontend work. Anthropic’s published same-prompt examples show visibly different interfaces when that guidance is added. They are vendor demonstrations of intended behavior, not independent evidence of a universal quality or conversion improvement.
Use general direction only where it does not conflict with approved system rules. If your organization has defined colors, typography, spacing, components, or accessibility requirements, a custom design-system Skill should carry those rules. The house system is authoritative; general aesthetic guidance is an optional layer around it.
| Need | Starting point | Important boundary |
|---|---|---|
| Explore a frontend direction | Anthropic frontend-design | Use it where no strict house system applies, or only in areas where it cannot override approved rules. |
| Follow a strict brand system | Custom design-system Skill | Supply the actual tokens, components, examples, and accessibility requirements. |
| Implement a Figma design | Figma design-to-code Skill with Figma MCP | Requires accessible design context and codebase access. It is not a guarantee of production readiness. |
For Figma-to-code work, Figma’s documented design-to-code Skill instructs the agent to request design context and a screenshot, inspect the codebase, and reuse suitable components and assets. A working Figma MCP connection and access to the relevant project are prerequisites. Treat the rendered implementation as a review target, not an approved production handoff.
Choose a visual direction
Use when the brief needs a deliberate aesthetic and no approved system supplies the answer. Review the result against the audience, accessibility needs, and project constraints.
Apply approved values
Use when the output must match named tokens, documented components, responsive rules, and accessibility guidance. Ask for missing source files instead of allowing invented values.
Design the custom Skill around one real workflow
Start with a recurring job, such as implementing an account settings panel using the team’s existing component library. Define what a finished result should contain. “Make every design better” is not a usable trigger because it does not identify the task, required inputs, or reviewable output.
Replace adjectives with values and references. “Use a modern blue” leaves the choice open. A useful rule names the approved token, prohibits unlisted colors, identifies the heading font and weight, and limits buttons to documented variants. Point to the actual token file, component inventory, approved screens, and accessibility guidance. If those files are unavailable to the current Claude surface, the Skill should report that limitation and request them.
The following is a hypothetical contract for a Skill. These fields are editorially proposed and are not required Anthropic frontmatter or a built-in validation schema:
---
name: product-ui-implementation
description: Use when implementing or revising product pages and components governed by the team design system.
---
# Inputs and rules
- token_version: 2.4.0
- component_source: src/components and the supplied component inventory
- typography: Use the approved heading family and documented weights.
- spacing_scale: Use spacing tokens from tokens.css; do not invent values.
- focus_style: Preserve the documented visible keyboard-focus treatment.
- banned_patterns: Unlisted colors, undocumented button variants, new dependencies.
# Output
List changed files, approved components and tokens used, and unresolved requirements.The design-system owner maintains the source values and resolves visual-rule conflicts. The implementation reviewer checks code, responsive behavior, and accessibility. The Skill can ask Claude to report exceptions, but its instructions do not independently enforce a JSON schema or prove that every rule was followed.
Build, install, and scope the Skill to its surface
Use this sequence: create a folder containing SKILL.md; validate the required name and description frontmatter; confirm every linked file exists; package and deploy it on the intended Claude surface; enable the required settings; then test a real matching task. Anthropic recommends keeping the main Skill body under 500 lines and moving detailed reference material into separate files. Some Anthropic cookbook material describes the full body as approximately under 5,000 tokens, but that is guidance rather than a universal API-enforced limit. See the Skill authoring guidance.
For Claude, the Help Center documents uploading a ZIP through Customize > Skills. Current Help Center documentation lists Skills for Free, Pro, Max, Team, and Enterprise when code execution is enabled. Team and Enterprise administrators may also need to allow Skills, file creation, or code execution.
Description limits vary by surface and documentation. Anthropic’s Platform and API documentation and the open specification allow descriptions up to 1,024 characters. A Claude Help Center creation article separately describes a 200-character limit for its flow. Keep the description concise, include what the Skill does and when it should activate, and validate the limit in the exact surface you use.
A Skill uploaded to Claude is not automatically synchronized with Claude Code or the API. Manage or deploy the package separately for each intended surface. Claude Code supports managed, user, project, and plugin-based Skill scopes; verify current name-collision behavior in the documentation for the installed version rather than relying on an copied precedence list.
For API use, follow the API Skills guide. API Skills run in an isolated environment without network access or runtime package installation, so required dependencies must already be available in the API container. Package behavior is surface-specific and should not be generalized from Claude or Claude Code to the API.
Test whether the Skill changes useful outcomes
Choose representative tasks from real work and run each both with and without the Skill under matched conditions: the same relevant model, brief, repository commit, and viewport. Include prompts that should activate the Skill and near-miss prompts that should not. If intended tasks fail to activate, revise the description and trigger language. If activation occurs but exact rules are ignored, improve the instructions or make the source material more accessible.
Separate deterministic checks from human judgment. A script or ordinary test can check whether token names resolve, a referenced file exists, a prohibited dependency was added, contrast requirements pass, or a required focus style is present. A person should assess visual hierarchy, brand fit, tone, audience suitability, and whether motion is distracting.
The following is a proposed evaluation record for one prompt execution. It is not a vendor feature. The run record identifies one generation attempt; each rendered screen is stored separately because a route or component at one viewport is a different observation.
{
"skill_version": "1.2.0",
"model": "model-under-test",
"prompt_id": "settings-panel-01",
"run_number": 2,
"baseline_or_skill": "skill",
"repository_commit": "illustrative-commit-id",
"rendered_screens": [
"screen-record-01"
]
}Give each run a unique identity containing skill_version, model, prompt_id, run_number, baseline_or_skill, and repository_commit. Store each screen separately with its route, viewport dimensions, screenshot reference, and parent run ID. If the same prompt is tested across several models, viewports, or repeated samples, those dimensions must remain in the run identity.
For concurrent evaluators, enforce uniqueness in the database with a constraint on the complete run key, or use a transactional upsert. A lookup followed by an insert is not race-safe. Do not use a run-level ID as a page-level or screen-level ID, and do not store aggregate quality claims in a raw observation record.
A single screenshot is evidence about one run, not proof that a Skill improves design quality. Report an improvement only after a defined prompt set, a matched baseline, a stated aggregation method, and human review of the relevant screens.
- Run baseline and Skill versions against the same prompts, model, repository state, and target viewport.
- Test intended triggers and near-miss prompts so accidental activation is visible.
- Verify tokens, components, focus treatment, responsive rules, referenced files, and dependency changes with deterministic checks where possible.
- Store run and rendered-screen records at their correct grain, with database-enforced uniqueness for concurrent tests.
- Have a reviewer assess rendered screens for hierarchy and brand fit, record the viewport, and retain the previous Skill version for rollback.
Compare multiple representative runs before deciding whether the Skill is useful. Preserve the prompt set, Skill version, model, repository state, and review notes so later changes can be compared fairly. Anthropic’s skill-creator package includes guidance for creating and evaluating Skills, but it does not guarantee an improvement for a custom design system. The cited SWE-Skills-Bench research evaluates software-engineering tasks, not frontend design quality, so it should not be used as proof for this workflow.
Maintain the Skill as part of the design system
Keep the canonical Skill source in version control. Record its version, the design-system release it describes, supported framework, supported components, owner, migration notes, and change history. Update it in the same review cycle as token or component changes where practical. Anthropic’s production Skill guidance supports evaluation, version control, pinned production versions, and rollback practices.
Review third-party Skill packages as software before enabling them. Read the instructions and inspect scripts, dependencies, filesystem access, network calls, external URLs, and any access to secrets. Preserve the package provenance, repository revision, reviewer, and approval date. Test it in an isolated project before granting production access.
A new instruction file does not validate the repository or approve generated changes. If an update regresses token checks, component usage, accessibility checks, or human review, return to the prior version while the design-system owner and technical reviewer resolve the issue.
If your team already uses ClickUp to assign design reviews and handoffs, the surrounding workflow can be documented through ClickUp setup and automation. This is a workflow-management option, not a claimed Claude Skills integration.
The operating rule is straightforward: use general design direction where the house system leaves room for choice, encode exact system rules in a focused Skill, and release it only after matched baseline testing, deterministic checks, and human review.