When a design task is ready to become a skill
A design agent skill packages a repeatable procedure, its required context, and its acceptance checks for a supported agent host. It is most useful when the task has a recognizable starting condition and a reviewable result. A broad instruction such as “make everything better” gives the agent too much ambiguity to reproduce a reliable workflow.
TDP’s agent-skills article describes turning a successful token audit into a reusable procedure. It also separates the skill from the connection to a tool: an integration provides access, while the skill explains how to use that access for a particular job.
Start with work you have already performed successfully. Capture the decisions that made the result useful before asking an agent to generalize them. The first version should solve one recurring problem well.
Step 1. Pick a narrow repeatable task
Choose something concrete, such as auditing whether a form uses approved spacing tokens. “Make good design” is too broad to evaluate. Write the trigger, required inputs, and expected output. Run the task manually once and keep the result as the reference your skill should reproduce.
Step 2. Describe the inputs and constraints
List the files or links the skill must inspect and what it should do when those sources are unavailable. Distinguish read-only auditing from changes to the product. If the workflow requires a designer’s decision, make that decision point explicit instead of asking the agent to fill the gap silently.
Step 3. Write an inspectable skill
The exact installation location and metadata depend on the agent. This example shows the content of a small SKILL.md; adapt it to the host’s documented format.
---
name: audit-spacing
description: Audit a screen against the product spacing tokens.
---
1. Read the token source and the target component.
2. List spacing values used by the component.
3. Compare each value with the approved token scale.
4. Report file, value, expected token, and visible impact.
5. Separate verified mismatches from suggestions.
6. Do not change files during the audit.
Output: findings table, evidence, and unresolved questions.
Step 4. Test a fresh case
Try the skill on a screen that was not used to write it. Include an intentional mismatch and one legitimate exception. Check whether the report identifies both correctly. A skill that reports every unusual value as a defect will create unnecessary work. Add an example that explains how approved exceptions should be handled.
Step 5. Maintain it with the workflow
Store the skill where your team versions its working rules. Update it when token paths or conventions change. Keep host-specific connection details separate from the durable design instructions where possible. Retest after meaningful edits and remove steps that no longer match how the team works.
Worked example: a token-audit skill
Suppose your team repeatedly finds hardcoded colors in new components. A useful skill can inspect a named component, compare its values with the approved token source, and propose a mapping with evidence. It should not automatically replace every matching hex value across the repository: identical values can serve different semantic roles.
Define the contract before writing instructions. The input is a component path and token source. The output is a table of observed values, proposed roles, evidence, and unresolved questions. The acceptance check is whether another reviewer can reproduce each finding and approve the mapping.
Task: audit token usage in a named component.
Read the component, its styles, and the approved token source.
Report literal values and existing token references.
For each proposed replacement, explain the semantic role.
Separate exact matches, inferred mappings, and unresolved cases.
Do not change files unless implementation was requested.
Finish with affected files and a verification plan.
The procedure is small enough to test. It also has a clear boundary: identifying a likely token is not the same as receiving approval for a product-wide migration.
Write the trigger as a job description
A useful description tells the host when the skill applies. Include the task, the kind of artifact involved, and the expected result. Avoid a long list of loosely related keywords that causes the skill to activate for every design request.
For example, “Audit component color and spacing values against the repository’s approved design tokens” is more specific than “Help with design systems.” Add a nearby non-example: choosing a brand palette from scratch is a different task and should not activate a token-replacement workflow.
Discovery and activation vary by host. Test both explicit invocation and an ordinary request that should match. If the host never loads the skill, inspect its supported location and format before rewriting the procedure itself.
Test good inputs, missing inputs, and near misses
| Test case | What the skill should do |
|---|---|
| Component and token source are present | Produce a grounded audit with source references |
| Token source is missing | Identify the missing input instead of inventing a palette |
| Two roles share the same value | Preserve the distinction until intent is known |
| Request is about a new brand identity | Stay outside the token-audit scope |
| Implementation is explicitly requested | Apply only the reviewed mapping and verify the result |
Keep the test cases with the skill or in its maintenance notes. A revised description can improve activation while accidentally broadening scope, so repeat the near-miss test after changes.
Package reusable evidence without freezing the project
Include a small example, an output template, and links to the current sources. Avoid copying the entire design system into the skill. That creates a second version which can silently fall behind. Project-specific rules should point to the repository’s maintained context.
A skill can capture a successful workflow, but it should not encode an accidental workaround as a permanent rule. During review, distinguish the steps that are generally necessary from those that only solved the original example. Keep tool-specific prerequisites explicit and name what happens when they are unavailable.
Share a reviewed version and keep learning
Give a teammate a fresh session and the same task. Compare the result with the accepted example, including omissions and unnecessary actions. Update the skill when the failure reveals a missing decision, then record the change so existing users understand it.
Use the TDP skills repository for existing procedures and installation guidance. The installation walkthrough covers choosing scope, verifying discovery, and reviewing the first run.
Completion checklist
- The task and trigger are specific.
- Required references are real and current.
- The output can be evaluated against an example.
- Missing information produces a clear limitation.
- The skill was tried on a fresh task with a known mismatch.
Common questions
Is a skill the same as an MCP connection?
A skill contains instructions. An MCP integration can provide access to tools or data. A workflow may use both, but installing instructions does not automatically grant access to Figma or another service.
Should every prompt become a skill?
Package the tasks you repeat and can evaluate. One-off exploration may not need the maintenance overhead of a reusable skill.
Sources and TDP resources
- TDP’s article on agent skills explains the original examples.
- TDP create-skill resource is a starting point; check its supported host before using it.