Creating Skills

This tutorial walks through building a skill from scratch, validating it, and publishing to the marketplace.

Prerequisites

• SiteSkills CLI installed and authenticated
• Familiarity with the target website you are building a skill for
• Understanding of CSS selectors

Step 1: Scaffold

Run the interactive scaffolding command:

siteskills init

Create a new SiteSkills skill
─────────────────────────────
Skill name (slug): my-awesome-skill
Display name: My Awesome Skill
Target domain(s): example.com
Category: productivity
Difficulty: easy
Requires auth? (y/N): n

Created my-awesome-skill/
  ├── SKILL.md
  ├── siteskills.json
  ├── README.md
  └── tests/
      └── test-basic.json

Step 2: Write SKILL.md

Open SKILL.md and define the navigation flow. This is what the agent reads at runtime.

Frontmatter

---
name: my-awesome-skill
description: "One-line description of what this skill does"
triggers:
  - "do something on example.com"
  - "automate example.com task"
---

Triggers are natural language phrases that tell agents when to activate this skill.

Prerequisites and Input Parameters

## Prerequisites
- Browser viewport at least 1024x768
- User must be on example.com

## Input Parameters
- `url` (required): The page URL to navigate to
- `option` (optional, default: "A"): Which option to select

Navigation Steps

Each step follows this pattern:

### Step 1: Navigate to Page
- **Goal:** Load the target page
- **Action:** Navigate to the provided URL
- **Expected state:** Page loads with main content visible
- **DOM hints:**
  - Primary: `#main-content`
  - Secondary: `.content-wrapper`
  - Text fallback: heading containing "Welcome"
- **Wait condition:** Element `#main-content` visible within 10 seconds
- **Fallback:**
  - If 404 -> report "Page not found"
  - If login redirect -> stop, report "Authentication required"

Key rules:

• Provide multiple DOM selectors in priority order (IDs, classes, text, ARIA)
• Always include a wait condition with a timeout
• Always include fallbacks with detection + recovery
• Be specific about what "success" looks like at each step

Verification

## Verification
The skill is successful when ALL of the following are true:
1. Confirmation message is visible
2. Page URL contains "/success"
3. Expected element is present in the DOM

Anti-Detection Notes

## Anti-Detection Notes
- Insert 0.5-2 second random delays between actions
- Scroll to elements naturally before clicking
- Do not reload the page unless necessary

Step 3: Fill siteskills.json

The scaffolded file has most fields pre-filled. Update these key sections:

Target

{
  "target": {
    "domains": ["example.com"],
    "url_patterns": ["https://example.com/page/*"],
    "requires_https": true,
    "last_verified": "2026-02-15T00:00:00Z",
    "verified_by": "manual"
  }
}

Compatibility

Declare which agents you have tested with:

{
  "compatibility": {
    "agents": [
      { "name": "claude-cowork", "min_version": null, "notes": "Tested" },
      { "name": "browser-use", "min_version": "0.3.0", "notes": "Needs Playwright" }
    ],
    "requires_auth": false,
    "requires_captcha_solver": false,
    "requires_proxy": false
  }
}

Failure Modes

Document every known failure with detection and recovery:

{
  "navigation": {
    "failure_modes": [
      {
        "id": "element-not-found",
        "description": "Target button not found on page",
        "detection": "element:#submit-btn not found within 5s",
        "recovery": "Fall back to text search for 'Submit' button",
        "probability": "low"
      }
    ]
  }
}

See the Template Standard for the complete field reference.

Step 4: Write README.md

The README is for human developers browsing the marketplace. Include:

# My Awesome Skill

A SiteSkills navigation skill for AI browser agents.

## What it does
Brief description of the automation.

## Supported Sites
- example.com

## Compatible Agents
| Agent | Min Version | Status |
|-------|------------|--------|
| Claude Cowork | Any | Tested |
| Browser Use | 0.3.0+ | Tested |

## Prerequisites
- List any requirements

## Installation
\```bash
siteskills install my-awesome-skill
\```

## Usage Examples
> "Do the thing on example.com"

Step 5: Validate

Run the local validator:

siteskills validate ./my-awesome-skill/

Validating my-awesome-skill...

Structure:
  SKILL.md found
  siteskills.json found (valid JSON, schema OK)
  README.md found
  No prohibited files
  Total size: 8.2 KB

Content:
  All target domains resolve
  3 navigation steps with fallbacks
  2 failure modes defined
  No suspicious patterns detected

Warnings:
  No test files in tests/ directory
  No screenshots provided

Result: PASS (ready to publish)

Fix any errors before publishing. Warnings are non-blocking but improve quality.

Step 6: Test Manually

Before publishing, test your skill with a real agent:

1. Install the skill locally in your agent's skills directory
2. Run the agent and trigger the skill with one of your trigger phrases
3. Verify each step executes correctly
4. Test the failure modes -- intentionally trigger edge cases
5. Update DOM selectors and fallbacks based on what you find

Step 7: Publish

siteskills publish ./my-awesome-skill/

Publishing my-awesome-skill v1.0.0...

  Validated locally (all checks pass)
  Packaged as zip (8.2 KB)
  Uploaded to SiteSkills
  Scan queued (estimated: 1-2 minutes)

Track status: https://siteskills.ai/dashboard/skills/abc123

The skill enters the automated scanning pipeline:

1. Structural validation -- file format, schema compliance
2. Static analysis -- pattern matching for suspicious content
3. LLM analysis -- AI review of navigation quality

Skills scoring 80+ are auto-approved. Lower scores go to manual review.

Updating a Published Skill

To push a new version:

1. Bump the version field in siteskills.json (follow semver)
2. Update target.last_verified to today's date
3. Add a CHANGELOG.md entry (optional but recommended)
4. Run siteskills publish again

siteskills publish ./my-awesome-skill/

The new version goes through the same scan pipeline. Previous versions remain available.

Tips

• Start simple. A 3-step skill that works reliably is better than a 15-step skill that breaks.
• Test on multiple screen sizes. Some sites serve different DOM for different viewports.
• Watch for A/B tests. Major sites change layouts frequently. Use text fallbacks, not just selectors.
• Document aggressively. Future you (and other developers) will thank you.
• Set last_verified honestly. It drives the auto-deprecation system.