How It Works

Everything you need to know about creating, publishing, and using AI agent skills.

What is uiskill?

uiskill is an open platform for packaging, sharing, and installing AI agent skills. A skill is a structured description of how an AI agent should behave in a specific context — it can be a set of UI interaction steps, a markdown document with guidelines, or a collection of design rules.

Skills are installed into your project as plain files (SKILL.md) that AI coding tools like Claude Code, Cursor, and Windsurf can read and act on. Think of it as npm for AI agent behavior— you publish once, and anyone can install and use your skill.

In short: uiskill turns expert knowledge into reusable, installable instructions that AI agents can follow.

Why use uiskill?

Reusable expertise

Encode team knowledge, UI patterns, and best practices into skills that anyone can install — no more copy-pasting prompts.

Works with your tools

Generates SKILL.md for Claude Code, .mdc for Cursor, and plain markdown for Windsurf. One skill, multiple tools.

Version controlled

Every publish creates a new version. Install a specific version or always get the latest. Roll back anytime.

Share across teams

Publish skills under your namespace. Team members install with one command and stay in sync.

How to use

Install the CLI

npx uiskill --help

No global install needed. Run directly with npx.

Browse and install skills

# Install a skill by name
npx uiskill install @fan/b2b-saas-sap-patterns

# Install a specific version
npx uiskill install @fan/b2b-saas-sap-patterns@1.0.1

This downloads the skill and generates a SKILL.md file in .claude/skills/. Reference files (if any) are placed alongside it.

Use with AI tools

Once installed, AI agents automatically pick up the skill files. The installed structure looks like:

.claude/skills/fan--b2b-saas-sap-patterns/
  SKILL.md                          # Main skill file
  references/                       # Optional reference files
    page-archetypes.md
    interaction-rules.md

Claude Code reads SKILL.mdand follows the instructions. For Cursor and Windsurf, use the "Copy" options on each skill's detail page.

Publish your own skills

Create a skill on the web UI or publish from the CLI:

# Login with your API token
npx uiskill login <your-token>

# Publish a SKILL.md directory (with optional references/)
npx uiskill publish ./my-skill/ --scope @my-namespace

# Or publish a JSON spec directly
npx uiskill publish ./spec.json --scope @my-namespace

You can also create skills directly from the web at uiskill.sh/your-username/new.

Skill types

uiskill supports three types of skills. Choose the one that best fits your use case.

Markdown Skill

markdown

A free-form markdown document with optional reference files. Ideal for encoding knowledge, guidelines, workflows, and patterns that AI agents should follow.

Best for:

-Enterprise UI patterns and interaction guidelines
-Project-specific coding standards and conventions
-Step-by-step workflow documentation with references
-Architecture decision records for AI context

---
name: b2b-saas-sap-patterns
description: "Enterprise B2B SaaS interaction patterns"
---

# B2B SaaS SAP Patterns

## Working Style
1. Start from the user's business task
2. Prefer predictable enterprise patterns
...

## Reference Files
- Read `references/page-archetypes.md` for layout patterns

Atomic Skill

atomic

A structured JSON spec that describes a specific UI interaction — which elements to find, what parameters to collect, and how to verify success. Designed for repeatable, automatable tasks.

Best for:

-Automating form submissions and data exports
-Standardizing multi-step UI workflows
-Defining reusable interactions with specific UI components
-Tasks with clear pre-conditions and success criteria

{
  "name": "Export Customer List",
  "kind": "atomic",
  "anchors": {
    "trigger": "@button(text='Export')",
    "container": "@table(name='customer_list')"
  },
  "parameters": {
    "type": "object",
    "properties": {
      "format": {
        "type": "string",
        "enum": ["excel", "csv", "pdf"]
      }
    }
  }
}

Design Rules

design-rules

A versioned collection of design constraints with conditions, scopes, severity levels, and examples. Use them to enforce consistency across your product's UI.

Best for:

-Enforcing page layout standards (list, detail, create flows)
-Defining form design constraints (grouping, field limits)
-Accessibility and usability requirements
-Team-wide design governance and review criteria

{
  "type": "design-rules",
  "name": "Core Page Rules",
  "rules": [{
    "id": "create-flow-page",
    "condition": "Form has more than 5 fields",
    "constraint": "Use a full page, not a modal",
    "severity": "warning",
    "examples": {
      "positive": ["Form split into sections"],
      "negative": ["20 fields in a single modal"]
    }
  }]
}

	Markdown Skill	Atomic Skill	Design Rules
Format	Markdown + YAML frontmatter	JSON spec	JSON spec
Reference files	Supported	-	-
Versioning	Auto-incremented	Auto-incremented	Explicit (semver)
Best for	Knowledge & guidelines	UI automation	Design governance
Publish from	Web UI / CLI	Web UI / CLI	Web UI / CLI