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.

uiskill supports the Anthropic Agent Skills standard natively — you can publish, install, and download skills in the same format used by Claude.ai and Claude Code. Skills can also bundle scripts, reference files, and declare MCP server dependencies.

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 (with YAML frontmatter)
  references/                       # Optional documentation files
    page-archetypes.md
    api-guide.md
  scripts/                          # Optional executable scripts
    validate.py

Claude Code reads SKILL.mdand follows the instructions. Agent Skills output the standard Anthropic format directly — compatible with Claude.ai upload. 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 four types of skills. Choose the one that best fits your use case.

Agent Skill

agent-skill

An Anthropic-standard skill with YAML frontmatter, step-by-step instructions, and optional bundled scripts and references. Compatible with Claude.ai, Claude Code, and the Anthropic Skills API. Supports MCP server declarations, tool permissions, and workflow patterns.

Best for:

-Multi-step workflow automation (sprint planning, onboarding, deployments)
-MCP-enhanced workflows with embedded best practices
-Document and asset creation with quality checks
-Domain-specific intelligence (compliance, QC, financial analysis)

---
name: sprint-planner
description: Manages sprint planning. Use when user says "plan sprint".
license: MIT
compatibility: Claude Code, Claude.ai
allowed-tools: "Bash(python:*) WebFetch"
metadata:
  mcp-server: linear
---

# Sprint Planner

## Instructions

### Step 1: Fetch Project Status
Call MCP tool: `list_projects`

### Step 2: Create Tasks
Create tasks with labels and estimates.

## Examples
User says: "Plan my Q4 sprint"
...

## Troubleshooting
Error: Connection refused
Solution: Verify MCP server is running

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"]
    }
  }]
}

	Agent Skill	Markdown Skill	Atomic Skill	Design Rules
Format	SKILL.md (Anthropic standard)	Markdown + YAML frontmatter	JSON spec	JSON spec
Bundled files	references, scripts, assets	references	-	-
MCP support	metadata.mcp-server	-	-	-
Tool permissions	allowed-tools field	-	-	-
Versioning	Auto-incremented	Auto-incremented	Auto-incremented	Explicit (semver)
Best for	Workflow automation & MCP	Knowledge & guidelines	UI automation	Design governance
Claude.ai compatible	Direct upload	Via copy	Via copy	Via copy
Publish from	Web / CLI / GitHub import	Web / CLI	Web / CLI	Web / CLI

Quality Validation

Every skill is validated on publish. The system checks for common issues and assigns a quality score (0-100). Validation errors block publishing; warnings are shown but don't prevent it.

What gets checked

- Name: must be kebab-case, no reserved words (claude, anthropic)
- Description: must include what + when (trigger phrases), no XML injection
- Body: should have structured headings, examples, troubleshooting
- Security: allowed-tools scope check, reserved name blocking

You can validate before publishing using the Validate button in any publish form, or call POST /api/skills/validate directly.

Import from GitHub

Import Anthropic-format skills directly from any public GitHub repository. The platform fetches the SKILL.md file, parses the YAML frontmatter, validates the spec, and publishes it to your namespace.

Supported URL formats:
  https://github.com/owner/repo
  https://github.com/owner/repo/tree/main/path/to/skill
  https://github.com/owner/repo/blob/main/skills/my-skill/SKILL.md

Access it from the Create dropdown on your profile page, or call POST /api/skills/import-github with {"url": "...", "scope": "your-namespace"}.