How to use the OpenClaw Design Audit agent skill

What does the openclaw-design-audit skill make the agent do?

An agent skill is a folder of instructions and reference files that an AI agent loads when a task matches the skill's description. This one tells the agent how to audit OpenClaw frontend code and rendered interfaces for drift from the Carapace design system.

The agent checks five kinds of problem and reports each finding with a file and line, a severity, and a suggested fix. It separates strict rule violations from matters of judgment, so a suggestion is not presented as a violation unless a documented rule makes it one.

• Carapace drift
• Token misuse
• Reimplemented UI primitives
• Accessibility problems
• Responsive layout defects
• Off-brand copy

How do you install the skill?

Download the ZIP file from the skill's page on this directory. Then choose one of two routes.

For a personal install, unzip the file into your ~/.claude/skills/ folder. For a single project, unzip it into that project's .claude/skills/ folder so it applies only to that repository.

If you use the Claude apps rather than a local folder, upload the ZIP under Settings, then Capabilities, then Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills

What do you need before running an audit?

The skill does not work on its own. It depends on access to your project and on a few other pieces. Check these before you ask for a review.

The skill expects the installed product guidance skill for the Carapace token contract. Use openclaw-carapace for new installs, or the openclaw-design-system compatibility alias if your lock file predates it.

• Access to the Carapace version installed in your consumer project and to its source repository
• The openclaw-carapace skill, or the openclaw-design-system alias, for the token contract
• A rendering or browser capability so the agent can inspect routes at desktop and mobile sizes
• GitHub access, only if you use the scheduled pull request delivery workflow

How do you trigger the skill with natural requests?

You do not need a special command. Describe the task in plain language and mention the design system so the agent matches the skill. The skill's description covers design reviews, compliance checks, and scheduled audit-and-fix workflows, so requests in those terms should load it.

The examples below are phrasing ideas, not fixed commands. Adjust them to your repository and routes.

• Run a design audit of the checkout pages against Carapace and list errors first.
• Review this branch for token misuse and reimplemented primitives before I open the pull request.
• Check the settings screens at desktop and mobile sizes for responsive defects.
• Do a design compliance review of the marketing copy for off-brand wording.
• Audit the frontend and apply only the narrow fixes that the fix policy allows, then leave the rest as a report.

How do you read the audit report?

The skill produces two files: design-audit.json for tools and design-audit.md for people. Each finding includes its file and line, category and severity, a stable rule ID, a concise remediation, a Carapace reference, and whether it is mechanical or judgment-based.

Findings are sorted by severity, then rule ID, file, and line. Every error is included. Warnings come before informational findings, and the concise report shows at most five non-error findings, with the rest summarised by count. If there are zero errors, zero warnings, and five or fewer informational findings, the result is treated as no significant drift.

• Errors: all are included
• Warnings: ranked before informational findings
• Informational: at most five shown in the concise report, the rest counted

What can the agent fix, and how do pull requests work?

The skill can apply fixes only when you ask and only when a change is narrow, deterministic, and covered by an existing rule. Allowed fixes include replacing a raw value with an equivalent canonical semantic token, adding a missing accessible label when intent is unambiguous, and repairing clipping or overflow without changing information architecture.

Copy, navigation, new components, broad visual redesign, and deletion of compatibility aliases need human review. For scheduled delivery, the skill opens a pull request against openclaw/clawhub using a stable automation branch such as automation/design-audit. The schedule and credentials live in the consumer repository's GitHub Actions workflow, not in the skill itself.

• Allowed automatic fixes: token replacements, alias replacements, established local primitives, missing accessible labels, overflow repair
• Human review required: copy, navigation, new components, broad redesigns, alias deletion, asset or licence questions
• Keep dependency, redesign, and audit fixes in separate pull requests

What are the safety notes?

The skill is listed as running scripts and using the network. Read the files in the ZIP before you install it, and check which scripts it would run in your environment. Do not give it credentials or repository write access you would not give a new contributor.

Do not use the skill for unattended automatic fixing. It can edit code and open pull requests on a schedule, so review each pull request before merging. Projects that do not use OpenClaw or Carapace should not use it, because its rules are specific to those conventions.

• Review the ZIP contents before installing
• Limit repository and GitHub permissions to what the workflow needs
• Review every automated pull request before merge