Best Practices for Prompting AI Agents Using UI Skills

To achieve deterministic, high-quality output from AI agents using the emilkowalski/skills framework, select the specific skill for your task, provide absolute paths to auxiliary files like AUDIT.md, and use the exact "Hard Rule" wording and output formats prescribed in each SKILL.md file.

The emilkowalski/skills repository packages expert-level UI knowledge into discrete, self-contained "skills" that function as strict operating manuals for AI agents. Each skill is defined in its own SKILL.md file and specifies the precise prompting conventions required to activate the correct reasoning patterns. Following these best practices for prompting AI agents using UI skills ensures the model adopts a deterministic posture and returns citations grounded in the repository's standards rather than generic advice.

Select the Appropriate Skill for Your Task

The repository contains specialized skills for distinct UI workflows. Choosing the correct skill is the first step in generating relevant output:

• review-animations: Performs strict motion audits against ten non-negotiable standards defined in skills/review-animations/SKILL.md.
• improve-animations: Generates prioritized remediation plans following a nine-step escalation hierarchy, requiring an AUDIT.md file path.
• pick-ui-library: Recommends component libraries based on concrete requirements like SSR compatibility and CSS variable support.
• animation-vocabulary: Maps vague motion descriptions to precise terminology.
• prototype and animate: Construct UI variations and complete animation specifications.

Each skill file lists its purpose upfront and defines the exact context required to execute effectively.

Structure Prompts for Deterministic Output

Lead with Intent, Follow with Structured Data

Keep prompts short but information-rich. Start with a one-sentence intent, then provide supporting data as bullet points or JSON blocks. Avoid narrative fluff that could distract the model from the skill's specific operating posture.

Reference Standards and Auxiliary Files Directly

When a finding requires a concrete value, instruct the agent to load it directly from STANDARDS.md rather than paraphrasing. According to skills/review-animations/SKILL.md, the agent must "load it whenever a finding needs a precise value or citation" for easing curves, durations, and spring configurations.

For remediation tasks, always provide the absolute path to AUDIT.md as required by skills/improve-animations/SKILL.md. Include concrete facts about your stack (e.g., "React + Framer Motion"), token conventions (e.g., "CSS variables"), and frequency maps (e.g., {"toasts": "high", "modals": "low"}).

Honor Skill Conventions and Hard Rules

Copy Verbatim Requirements

Many skills embed "Hard Rule" clauses that must be copied verbatim into your prompt (e.g., "Hard Rule 4"). These rules forbid the model from writing code, fixing unrelated bugs, or making assumptions beyond provided data. Explicitly referencing these prohibitions keeps the model on track.

Respect Prescribed Output Formats

Each skill mandates specific output structures that must be requested explicitly:

• review-animations: Expects a markdown table followed by a verdict grouped by impact tier.
• improve-animations: Returns a prioritized remediation plan.
• animation-vocabulary: Returns a single matching term.

Requesting these exact formats ensures the agent structures its response according to the skill's design.

Respect Escalation Hierarchies

For remediation workflows, never jump to advanced fixes without exhausting simpler options. The improve-animations skill defines a nine-step hierarchy: delete → reduce → fix easing → adjust duration → check performant properties → verify reduced motion → stagger children → isolate paint → optimize composite.

Your prompt should explicitly instruct the agent to follow this order, ensuring systematic optimization rather than superficial patches.

Practical Implementation Examples

Execute skills via the CLI or structured JSON payloads:

# Review an animation diff against standards

npx skills@latest run review-animations \
  --diff path/to/file.css:45 \
  --standards ./skills/review-animations/STANDARDS.md

{
  "skill": "improve-animations",
  "context": {
    "audit_path": "./skills/improve-animations/AUDIT.md",
    "stack": "React + Framer Motion",
    "library": "framer-motion",
    "token_conventions": "css variables",
    "frequency_map": {"toasts": "high", "modals": "low"}
  },
  "prompt": "Generate a prioritized remediation plan following the hierarchy in the skill."
}

# Select a UI library based on requirements

npx skills@latest run pick-ui-library \
  --requirements "lightweight, supports CSS-variables, SSR-compatible"

# Convert vague descriptions to precise terminology

npx skills@latest run animation-vocabulary \
  --description "the bouncy thing when a popover opens"

Summary

• Select the appropriate skill from the emilkowalski/skills repository based on your specific task (review, remediate, select, or define).
• Provide absolute paths to auxiliary files like AUDIT.md and reference STANDARDS.md directly for precise values.
• Use exact wording for "Hard Rules" and required output formats (tables, verdicts, hierarchies) defined in each SKILL.md file.
• Honor the nine-step escalation hierarchy in improve-animations by following the prescribed order: delete, reduce, fix easing, then proceed to duration and property adjustments.
• Explicitly state prohibitions to prevent the model from writing code or making assumptions beyond the provided data.

Frequently Asked Questions

How do I prevent an AI agent from hallucinating when using UI skills?

Provide absolute file paths to reference documents like STANDARDS.md and AUDIT.md, and include verbatim "Hard Rule" clauses from the skill files that explicitly forbid assumptions. According to skills/review-animations/SKILL.md, loading standards directly whenever a finding needs citation keeps the model grounded in concrete values rather than generic knowledge.

What information should I include when prompting the improve-animations skill?

Include the absolute path to your AUDIT.md file, your exact technology stack (e.g., React + Framer Motion), your token convention system (e.g., CSS variables), and a frequency map indicating usage patterns (e.g., {"toasts": "high", "modals": "low"}). This complete context enables the nine-step hierarchy remediation defined in skills/improve-animations/SKILL.md.

Why must I follow the exact wording in SKILL.md files?

The emilkowalski/skills repository encodes deterministic "operating postures" through specific phrasing, particularly in "Hard Rule" blocks and output format requirements. Deviating from the prescribed wording in skills/review-animations/SKILL.md or skills/improve-animations/SKILL.md allows the model to default to generic patterns, reducing the precision and reliability of the UI recommendations.

What is the correct order for animation remediation fixes?

As implemented in skills/improve-animations/SKILL.md, you must follow the nine-step hierarchy: first consider deletion, then reduction, then fixing easing, adjusting duration, checking performant properties, verifying reduced motion support, staggering children, isolating paint, and finally optimizing composite layers. Jumping ahead skips foundational optimizations that might resolve issues more efficiently.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}