Skip to main content

​
Overview

Claude Code uses Anthropic’s Skills specification with full support for frontmatter metadata, arguments, and reference files. Impeccable delivers the richest feature set for Claude Code, preserving all metadata and providing native argument support.

​
Installation

1

Download the bundle

Visit impeccable.style and download the Claude Code bundle, or copy from the repository:
cp -r dist/claude-code/.claude your-project/
2

Verify installation

In Claude Code, type /audit - the skill should autocomplete with its description.
Claude Code supports both project-specific (.claude/ in project root) and global (~/.claude/ in home directory) skills. Project-specific skills take precedence.

​
File Structure

Claude Code follows the Anthropic Skills directory structure: 
your-project/
└── .claude/
    └── skills/
        ├── audit/
        │   └── SKILL.md
        ├── normalize/
        │   └── SKILL.md
        └── frontend-design/
            ├── SKILL.md
            └── reference/
                ├── typography.md
                ├── color-and-contrast.md
                ├── spatial-design.md
                ├── motion-design.md
                ├── interaction-design.md
                ├── responsive-design.md
                └── ux-writing.md

​
Skill Format

Claude Code skills use comprehensive YAML frontmatter: 
---
name: audit
description: Perform comprehensive audit of interface quality
user-invokable: true
args:
  - name: area
    description: The feature or area to audit (optional)
    required: false
allowed-tools:
  - grep
  - read
  - write
compatibility:
  requires:
    - web
---

Skill instructions here with {{area}} placeholders...

​
How Arguments Work

Claude Code has native argument support with placeholder injection:

​
Argument Syntax

/audit
When you provide an argument, Claude injects it into the skill body at {{area}} placeholders: 
# Source
Audit the {{area}} for quality issues.

# Becomes (with /audit checkout form)
Audit the checkout form for quality issues.

​
Multiple Arguments

Claude Code supports multiple named arguments: 
args:
  - name: component
    description: The component to adapt
    required: true
  - name: device
    description: Target device (mobile, tablet, desktop)
    required: false
Invoke with space-separated values: 
/adapt header mobile

​
Optional vs Required

The required field in frontmatter indicates whether an argument must be provided. Claude validates this and prompts for missing required arguments.

​
Provider-Specific Transformations

Claude Code receives the full-featured output with minimal transformations:

​
1. Preserve All Metadata

All frontmatter fields are preserved: 
name: audit
description: Comprehensive quality checks
user-invokable: true
args: [...]
allowed-tools: [...]
compatibility: {...}
metadata: {...}
license: Apache 2.0

​
2. Native Placeholder Support

Argument placeholders remain as {{argname}}: 
Audit the {{area}} for quality issues. Focus on:
- Accessibility
- Performance

​
3. Reference Files

Reference files are copied into each skill’s reference/ subdirectory with full content preserved.

​
Usage Examples

​
Basic Command

/audit
Runs audit on entire interface (no argument provided).

​
With Argument

/audit checkout form
Audits only the checkout form component.

​
Multi-Argument Command

/adapt navigation mobile
Adapts the navigation component for mobile devices.

​
Complex Workflow

# Step 1: Identify issues
/audit

# Step 2: Fix inconsistencies
/normalize

# Step 3: Improve performance
/optimize

# Step 4: Final polish
/polish

​
Available Skills

Impeccable includes 17 user-invokable skills for Claude Code:
SkillArgumentsPurpose
/audit[area]Technical quality checks (a11y, performance, responsive)
/critique[design]UX design review (hierarchy, clarity, emotional resonance)
/normalize[scope]Align with design system standards
/polish[component]Final pass before shipping
/distill[feature]Strip to essence
/clarify[copy]Improve unclear UX copy
/optimize[target]Performance improvements
/harden[flow]Error handling, i18n, edge cases
/animate[element]Add purposeful motion
/colorize[component]Introduce strategic color
/bolder[section]Amplify boring designs
/quieter[section]Tone down overly bold designs
/delight[interaction]Add moments of joy
/extract[pattern]Pull into reusable components
/adapt[component] [device]Adapt for different devices
/onboard[flow]Design onboarding flows
/teach-impeccable-One-time setup: gather design context

​
Advanced Features

​
Allowed Tools

Claude Code respects allowed-tools in frontmatter to constrain which tools a skill can use: 
allowed-tools:
  - grep
  - read
  - write
  - edit
This prevents skills from running arbitrary commands or accessing network resources.

​
Compatibility Requirements

The compatibility field specifies environmental requirements: 
compatibility:
  requires:
    - web
    - node
  optional:
    - tailwind
Claude can warn users if requirements aren’t met.

​
Skill Metadata

Custom metadata helps organize and categorize skills: 
metadata:
  category: quality
  domain: frontend
  version: 1.0.0
  tags:
    - accessibility
    - performance

​
Quirks & Best Practices

​
Skill Discovery

Claude Code automatically discovers skills in:
  1. .claude/skills/ (project-specific, higher priority)
  2. ~/.claude/skills/ (global, lower priority)
No manual registration needed.

​
Argument Validation

Claude validates required arguments before executing the skill. If a required argument is missing, Claude prompts the user for it.

​
Reference Skill Invocation

User-invokable skills explicitly reference the frontend-design skill: 
**First**: Use the frontend-design skill for design principles and anti-patterns.
This ensures Claude loads the comprehensive design knowledge before executing the task.

​
Combining Skills

Claude Code excels at chaining skills: 
# Quality workflow
/audit → /normalize → /optimize → /polish

# Design workflow  
/critique → /bolder → /colorize → /animate → /delight

​
Troubleshooting

​
Skills Not Found

1

Check file structure

Ensure .claude/skills/{name}/SKILL.md exists
2

Validate YAML

Use a YAML validator to check frontmatter syntax
3

Check name field

The name in frontmatter must match the directory name
4

Restart Claude Code

Reload the window to refresh skill cache

​
Arguments Not Injecting

If {{argname}} appears literally in output:
  1. Verify the argument name matches frontmatter exactly
  2. Ensure user-invokable: true is set
  3. Check that you’re using the correct invocation syntax

​
Permission Errors

If skills can’t read/write files:
  1. Check file permissions on .claude/ directory
  2. Verify allowed-tools includes necessary tools
  3. Ensure Claude Code has filesystem access

​
Migration from Other Providers

​
From Cursor

Claude Code adds argument injection support: 
# Cursor (append-only)
/audit checkout form
# Claude receives: "Run audit. checkout form"

# Claude Code (injection)
/audit checkout form  
# Claude receives: "Run audit on checkout form."

​
From Gemini CLI

Claude Code uses named arguments instead of {{args}}: 
# Gemini (single args string)
Prompt: Audit {{args}}

# Claude Code (named arguments)
args:
  - name: area
Prompt: Audit {{area}}

​
From Codex CLI

Claude Code uses {{argname}} instead of $ARGNAME: 
# Codex
Audit $AREA for issues

# Claude Code
Audit {{area}} for issues

​
Best Practices

​
1. Use Descriptive Arguments

✅ Good
args:
  - name: component
    description: The UI component to analyze
    required: false

❌ Bad
args:
  - name: x
    description: thing

​
2. Make Arguments Optional

Design skills to work with or without arguments: 
Audit {{area}}. If no area specified, audit the entire interface.

​
3. Leverage Reference Skills

Explicitly invoke comprehensive skills like frontend-design: 
**First**: Use the frontend-design skill to understand anti-patterns.
**Then**: Apply that knowledge to the current task.

​
4. Constrain Tool Access

Use allowed-tools to limit what each skill can do: 
# Design review skill (read-only)
allowed-tools:
  - grep
  - read

# Refactoring skill (read-write)
allowed-tools:
  - grep
  - read
  - write
  - edit

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us