Turn Design Workflows into SKILL.md Playbooks for Claude Code and Codex
Package repeatable design and accessibility checks into a reusable agent skill.
You may find yourself explaining the same things whenever your team builds a new screen: inspect the existing project first, reuse its buttons and color tokens, and check keyboard and narrow-screen behavior. Instead of pasting those directions into every prompt, put them in a SKILL.md file. Claude Code or Codex can read the playbook when it is relevant and reuse the process.
A skill does not make design decisions for the model. It is a practical way to communicate a team's repeated judgments and definition of done.
SKILL.md and Agent Skills Structure
The Agent Skills standard centers on a folder containing SKILL.md. The YAML frontmatter requires name and description; the body explains when to use the skill and what steps to follow. Add examples, checklists, scripts, or other supporting files when needed.
Claude Code and Codex differ in where they discover skills and which extensions they support, but both use SKILL.md for reusable guidance. Claude Code documents that a skill's body loads when it is used. Codex also uses a skill's name and description to assess relevance before loading the full instructions. Make the description specific about the requests that should trigger the workflow.
Use Cases for Design Skills
A skill is unnecessary for a one-off task or an approach that has not been agreed on yet. It is useful when: multiple screens or projects share the same review sequence; the team repeatedly misses accessibility, responsive, or state requirements; you want a consistent process rather than a particular visual outcome; and the procedure is stable enough to describe.
“Make a beautiful card UI” is too broad. “Check the existing tokens first, define the card's default, loading, and error states, then review the narrow-screen layout and keyboard focus” is a repeatable workflow.
SKILL.md Instruction Structure
1. Skill Invocation Conditions
Use description to say what kind of request should bring the skill into consideration. “Make good UI” is too broad; a narrow, specific request may prevent the skill from being selected when it is needed.
2. Project Inspection
Name the context to check before work begins: the framework, existing components and tokens, accessibility requirements, and target screen sizes. Finding existing patterns first can prevent unnecessary duplication.
3. Design Workflow Steps
Write actionable instructions with verbs. “Keep the design consistent” is vague. “Search for existing button variants and color tokens, and reuse a suitable pattern if one exists” is actionable.
4. Validation and Completion Criteria
Completion criteria should describe how to review the result. For example, check that key actions remain available at different viewport widths, required fields show errors, and the main flow works using only a keyboard.
Design Skill Example
This example describes a small workflow for extending an existing product UI. Adapt the name and review steps to your project.
---
name: product-ui-workflow
description: Use when adding or changing a screen or component in an existing web product. Inspect its UI conventions first, then review accessibility, responsive behavior, and states.
---
## Product UI workflow
1. Before editing, inspect the framework, existing components, tokens, page structure, and relevant UX requirements.
2. Look for a reusable existing pattern. If a new pattern is needed, state the user problem it solves in one sentence.
3. Define the relevant default, loading, empty, error, and disabled states before implementation.
4. Prefer existing tokens and copy conventions. Explain why if you introduce a new color, spacing value, or component variant.
5. Check that content and actions remain available on narrow and wide screens.
6. Review keyboard focus, interaction order, accessible names, and error messages.
7. Summarize the changed UI and behavior, checks performed, and any remaining limitations.
This file does not guarantee a finished interface. It cannot decide which component is appropriate, how an error should sound, or which information should take priority on a small screen without product context. A skill helps the team remember its criteria and repeat its review.
Skill Paths for Claude Code and Codex
Claude Code's documentation places project skills at .claude/skills/<skill-name>/SKILL.md and personal skills at ~/.claude/skills/<skill-name>/SKILL.md. The folder name is also used for direct invocation as /skill-name.
Codex can use repository skills at .agents/skills/<skill-name>/SKILL.md and personal skills at ~/.agents/skills/<skill-name>/SKILL.md. You can also create and manage skills in the Codex app. A repository skill can be versioned with the code so teammates can use the same workflow; a personal skill stays in that person's environment. Product discovery rules and setup locations can change, so check the current official docs before distributing instructions to a team.
Maintaining Design Skill Instructions
- Separate facts from procedures. Put longer token references in a separate file when useful, and tell the skill when to read it.
- Do not assume the project already has a particular component. Tell the agent to search for one first.
- Avoid instructions that require tools or files the agent may not have. Ask for missing context or limit the work to supplied materials.
- Describe exceptions. If existing tokens cannot meet a requirement, explain what to document and review rather than blindly following them.
- Improve the skill from real use: clarify skipped steps and remove broad guidance that does not help the task.
Pre-Share Skill Checklist
- Can someone tell from the name and description which requests should use this skill?
- Does the first step inspect the actual project?
- Are the steps written as concrete actions?
- Does the review include states, keyboard use, and responsive behavior as well as visual finish?
- Does the skill avoid assuming access to unavailable tools or files?
- Will the team keep it in version control so others can review and improve it?
Moving repeated explanations into a skill reduces the need to write long prompts from scratch. It also makes the team's quality criteria and remaining human decisions easier to see.