How AI Agents Can Use the 'skills' CLI Tool with Design Libraries

AI agents can invoke the skills CLI tool to programmatically access design library specifications by calling sub-commands like skills pick-ui-library --json, which returns a structured JSON payload of UI primitives, motion specs, and interaction guidelines.

The skills repository by Emil Kowalski provides a machine-readable interface to design knowledge through a command-line tool that parses Markdown-based skill definitions. This makes it possible for AI agents to consume design system documentation as structured data rather than unstructured text, enabling precise integration into code generation and design review workflows.

How the Skills CLI Works

The skills CLI operates on a simple but powerful model: Markdown files become executable specifications.

In skills/pick-ui-library/SKILL.md, the UI library skill defines components, motion parameters, and styling tokens under predictable headings. When the CLI runs, it:

1. Discovers all skill definitions by recursively scanning skills/**/*.md

2. Parses Markdown sections (e.g., ## UI components & primitives, ## Motion & visuals) into JSON key/value pairs

3. Exposes a sub-command matching each folder name (pick-ui-library, prototype, improve-animations)

4. Outputs deterministic JSON to STDOUT for programmatic consumption

Because the output schema is consistent, AI agents can reliably extract specific design properties without complex natural language processing.

Core Design Library Skills

The repository separates design concerns into modular skills that agents can combine flexibly:

Skill	CLI Command	What It Provides
UI Library Selection	skills pick-ui-library	UI components & primitives, Motion & visuals, Charts, Interaction & performance, State & styling
Prototyping Workflow	skills prototype	Markup, Styles, Rules, Behavior contract, Reference wiring
Animation Improvement	skills improve-animations	Recon, Audit, Vet, Write plans phases

Each skill is defined in its respective SKILL.md file under the skills/ directory, with skills/pick-ui-library/PICKER.md providing additional detailed markup guidance referenced by the prototype workflow.

Practical Usage Patterns for AI Agents

Discovering Available Skills

Before selecting a design library, agents can enumerate capabilities:

$ skills list
pick-ui-library
prototype
improve-animations
review-animations
animate
...

This returns plain text names that map directly to valid sub-commands.

Retrieving UI Library Specifications

The primary integration point for design library access:

$ skills pick-ui-library --json
{
  "UI components & primitives": ["Button", "Input", "Card", "Select", "Dialog"],
  "Motion & visuals": {
    "easing": "ease-out",
    "duration": "150-300 ms",
    "springs": true
  },
  "Charts": ["Bar", "Line", "Pie", "Area"],
  "Interaction & performance": {
    "interruptibility": "high",
    "accessibility": "WCAG-2.1"
  },
  "State & styling": ["Theme", "Tokens", "Dark mode"]
}

The --json flag ensures machine-parseable output. Without it, the CLI may provide human-readable formatting.

Consuming Output in Python Agents

A typical AI agent implementation:

import json
import subprocess

def get_design_library(skill_name: str) -> dict:
    """Fetch a design library skill as structured data."""
    result = subprocess.run(
        ["skills", skill_name, "--json"],
        capture_output=True,
        text=True,
        check=True,
    )
    return json.loads(result.stdout)

# Usage in code generation pipeline

ui_lib = get_design_library("pick-ui-library")

component_prompt = f"""Generate a React component using: {', '.join(ui_lib['UI components & primitives'])}.

Motion requirements:
- Easing: {ui_lib['Motion & visuals']['easing']}
- Duration: {ui_lib['Motion & visuals']['duration']}
- Springs enabled: {ui_lib['Motion & visuals']['springs']}

Accessibility: {ui_lib['Interaction & performance']['accessibility']}
"""

Chaining Multiple Skills

Complex workflows combine design library specs with prototyping or animation guidance:

# Fetch specifications in parallel

skills pick-ui-library --json > ui.json
skills prototype --json > proto.json
skills improve-animations --json > anim.json

A merge script for downstream consumption:

import json
import sys

def merge_skills(*paths: str) -> dict:
    """Combine multiple skill JSON outputs."""
    merged = {}
    for path in paths:
        with open(path) as f:
            merged.update(json.load(f))
    return merged

if __name__ == "__main__":
    spec = merge_skills(*sys.argv[1:])
    print(json.dumps(spec, indent=2))

Integration with LLM Orchestration Platforms

The JSON-only output makes skills compatible with any agent architecture. A LangChain-style workflow:

steps:
  - name: Retrieve design system
    command: skills pick-ui-library --json
    output: ui_spec
    
  - name: Retrieve prototyping rules
    command: skills prototype --json  
    output: proto_spec
    
  - name: Generate component
    model: gpt-4
    prompt: |
      Given these design specifications:
      {{ ui_spec | tojson }}
      
      And these prototyping constraints:
      {{ proto_spec | tojson }}
      
      Write a TypeScript React component for a user profile card.

Key Source Files for Reference

File Path	Purpose
skills/pick-ui-library/SKILL.md	UI library definition with components, motion, charts, and styling tokens
skills/pick-ui-library/PICKER.md	Detailed picker component markup and styling guide
skills/prototype/SKILL.md	Step-by-step interactive prototype workflow
skills/improve-animations/SKILL.md	Animation audit and improvement methodology
skills/review-animations/STANDARDS.md	"Ten Non-Negotiable Standards" for animation quality
skills/animate/SKILL.md	Core animation decision framework referenced by other skills

These Markdown files are the source of truth that the CLI parses. The hierarchical heading structure (## Section name) determines the JSON schema, ensuring that skills pick-ui-library --json always returns the same top-level keys regardless of content updates.

Summary

• The skills CLI converts Markdown skill definitions into structured JSON via sub-commands like skills pick-ui-library --json
• AI agents consume this output programmatically to access UI primitives, motion specs, and interaction guidelines
• The modular skill architecture allows flexible combination of design libraries, prototyping workflows, and animation standards
• Because output is language-agnostic JSON, integration works with Python, Node.js, or specialized LLM orchestration platforms
• Key files like skills/pick-ui-library/SKILL.md and skills/prototype/SKILL.md define the parseable content that drives the CLI

Frequently Asked Questions

What output format does the skills CLI produce?

The skills CLI produces deterministic JSON when invoked with the --json flag. Each Markdown section heading becomes a top-level JSON key, with the section content as its value. This predictable schema allows AI agents to access specific properties like Motion & visuals or UI components & primitives without parsing ambiguity.

Can AI agents combine multiple design library skills?

Yes. Agents can chain CLI calls to retrieve multiple skill specifications—such as skills pick-ui-library --json for component definitions and skills prototype --json for implementation workflows—then merge the resulting JSON objects in their processing pipeline. This composability lets agents assemble complete design-to-code workflows from modular sources.

Does the skills CLI require a specific programming language?

No. The CLI is language-agnostic: it reads Markdown files and prints JSON to STDOUT. Any AI agent implementation—whether Python, Node.js, Rust, or a hosted LLM platform—can invoke the binary and parse the output. This design prioritizes interoperability across diverse agent architectures.

Where are the design library specifications defined?

All specifications reside in Markdown files under the skills/ directory, with each skill in its own folder. For design libraries specifically, skills/pick-ui-library/SKILL.md defines UI primitives and motion guidelines, while skills/pick-ui-library/PICKER.md provides detailed component-level documentation. The CLI discovers these automatically through recursive file scanning.

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