Template Standard (SST v1.0)

The SiteSkills Template Standard defines the structure of every skill on the platform. Every component -- backend, CLI, scanner, agents -- depends on this format.

Design Principles

1. SKILL.md superset -- every SiteSkills skill is a valid Anthropic SKILL.md. Agents that understand SKILL.md can use SiteSkills skills without modification.
2. Human-readable first -- a developer understands what a skill does by reading the files. No proprietary formats.
3. Machine-parseable -- siteskills.json provides structured metadata validated with JSON Schema.
4. Self-contained -- a skill directory is a complete, portable unit. Copy it anywhere and it works.
5. Versioned -- skills declare their schema version. The standard evolves without breaking existing skills.
6. Testable -- skills include expected outcomes for automated verification.
7. Secure by design -- no executable code in skills. SKILL.md is instructions, not code.

Directory Structure

skill-name/
├── SKILL.md              # REQUIRED -- navigation flow definition
├── siteskills.json        # REQUIRED -- machine-readable metadata
├── README.md              # REQUIRED -- human documentation
├── tests/                 # RECOMMENDED -- automated test cases
│   ├── test-happy-path.json
│   ├── test-auth-required.json
│   └── test-edge-cases.json
├── screenshots/           # OPTIONAL -- expected visual states
│   └── step-1-product-page.png
├── locale/                # OPTIONAL -- localized versions
│   ├── de/
│   │   └── SKILL.md
│   └── fr/
│       └── SKILL.md
├── CHANGELOG.md           # OPTIONAL -- version history
└── LICENSE                # OPTIONAL -- defaults to MIT

Constraints

Rule	Limit
Maximum total size (zipped)	5 MB
Maximum file count	50 files
Allowed file types	.md, .json, .png, .jpg, .txt, .yaml, .yml
Prohibited	.js, .py, .sh, .bat, .exe, .dll, .so, any executable
Symlinks	Not allowed
Path traversal (../)	Not allowed
Directory name	Lowercase, hyphens only, 3-100 chars
Text encoding	UTF-8

siteskills.json Schema

The machine-readable metadata file. Validated against a Zod schema on upload.

Full Example

{
  "$schema": "https://siteskills.ai/schema/v1.0.json",
  "schema_version": "1.0",

  "skill": {
    "name": "amazon-add-to-cart",
    "display_name": "Amazon -- Add Product to Cart",
    "description": "Navigates Amazon product pages and adds items to cart with specified quantity, handling variant selection and availability checks.",
    "long_description": "A comprehensive skill for AI browser agents to reliably add products to an Amazon shopping cart...",
    "version": "1.2.0",
    "author": {
      "name": "siteskills-official",
      "display_name": "SiteSkills Official",
      "siteskills_id": "usr_official",
      "url": "https://siteskills.ai/users/siteskills-official"
    },
    "license": "MIT",
    "created": "2026-02-10T00:00:00Z",
    "updated": "2026-02-15T12:00:00Z"
  },

  "target": {
    "domains": ["amazon.com", "amazon.co.uk", "amazon.de"],
    "url_patterns": ["https://*.amazon.*/dp/*", "https://*.amazon.*/gp/product/*"],
    "excluded_urls": ["https://*.amazon.*/kindle-dbs/*"],
    "requires_https": true,
    "last_verified": "2026-02-01T00:00:00Z",
    "verified_by": "manual",
    "site_notes": "Amazon frequently A/B tests layouts."
  },

  "compatibility": {
    "agents": [
      { "name": "claude-cowork", "min_version": null, "notes": "Works with default Cowork settings" },
      { "name": "browser-use", "min_version": "0.3.0", "notes": "Requires Playwright backend" },
      { "name": "stagehand", "min_version": "3.0.0", "notes": "Leverage auto-caching" }
    ],
    "requires_auth": true,
    "auth_type": "session",
    "auth_notes": "User must be logged into Amazon.",
    "requires_captcha_solver": false,
    "requires_proxy": false,
    "requires_cookies": true,
    "requires_javascript": true,
    "viewport_requirements": {
      "min_width": 1024,
      "min_height": 768
    }
  },

  "navigation": {
    "total_steps": 5,
    "estimated_actions": 8,
    "estimated_time_seconds": 15,
    "difficulty": "medium",
    "interaction_types": ["click", "select_dropdown", "wait_for_element", "verify_text"],
    "failure_modes": [
      {
        "id": "out-of-stock",
        "description": "Product or variant is out of stock",
        "detection": "text:Currently unavailable OR button:Add to Cart[disabled]",
        "recovery": "Report to user with available alternatives",
        "probability": "medium"
      }
    ],
    "anti_detection": {
      "timing": { "min_delay_ms": 500, "max_delay_ms": 2000, "between_actions": true },
      "behavioral": ["Scroll naturally before clicking", "Wait for full page load + 1s"]
    }
  },

  "categories": ["e-commerce", "shopping"],
  "tags": ["amazon", "cart", "add-to-cart", "checkout"],

  "pricing": { "model": "free", "price_usd": null },
  "dependencies": { "skills": [], "notes": "Pair with amazon-login if not authenticated." }
}

Field Reference

Field	Required	Type	Description
schema_version	Yes	string	Always "1.0" for this version
skill.name	Yes	string	URL-safe slug, 3-100 chars, lowercase + hyphens
skill.display_name	Yes	string	Human-readable name, max 200 chars
skill.description	Yes	string	One-paragraph summary, max 500 chars
skill.long_description	No	string	Detailed description, max 2000 chars
skill.version	Yes	string	Semantic versioning (MAJOR.MINOR.PATCH)
skill.author.name	Yes	string	SiteSkills username
skill.license	Yes	string	SPDX identifier (MIT, Apache-2.0, etc.)
target.domains	Yes	string[]	Domains this skill works on (1-20)
target.url_patterns	Yes	string[]	URL glob patterns with wildcards
target.last_verified	Yes	ISO date	When last tested against live site
compatibility.agents	Yes	object[]	Compatible agents with optional versions
compatibility.requires_auth	Yes	boolean	Whether user must be logged in
navigation.total_steps	Yes	integer	Number of steps in SKILL.md
navigation.difficulty	Yes	enum	easy, medium, hard, expert
navigation.failure_modes	Yes	object[]	Known failures with detection/recovery
categories	Yes	string[]	From allowed list (1-3)
tags	Yes	string[]	Free-form tags (1-20, each 2-50 chars)
pricing.model	Yes	enum	free, paid, freemium

Allowed Categories

Category	Description
e-commerce	Online shopping, product listings, checkout
finance	Banking, payments, trading
government	Government portals, tax, benefits
healthcare	Patient portals, appointments, prescriptions
travel	Flights, hotels, car rental
food-delivery	Restaurant ordering, grocery delivery
social-media	Social networks, messaging
productivity	Workspace tools, project management
education	Learning platforms, course enrollment
real-estate	Property search, listings
job-search	Job boards, applications
insurance	Quotes, claims, policy management
shipping	Package tracking, shipping labels
legal	Court filings, legal documents
utilities	Utility bills, service setup
entertainment	Streaming, gaming, tickets
other	Anything not covered above

SKILL.md Format

The navigation flow file that agents read. Follows the Anthropic SKILL.md format with browser-navigation enhancements.

Structure

---
name: skill-slug-here
description: "One-line description matching siteskills.json"
triggers:
  - "natural language phrase that activates this skill"
  - "another trigger phrase"
---

# Skill Display Name

## Prerequisites
What must be true before execution.

## Input Parameters
What the user needs to provide.

## Navigation Flow

### Step 1: Step Name
- **Goal:** What this step accomplishes
- **Action:** What the agent should do
- **Expected state:** Page state after the action
- **DOM hints:** CSS selectors in priority order
- **Fallback:** Detection + recovery if action fails
- **Wait condition:** What to wait for before proceeding

### Step 2: Step Name
(repeat pattern)

## Verification
How to confirm the skill completed successfully.

## Known Issues
Site-specific quirks and workarounds.

## Anti-Detection Notes
Timing and behavioral guidelines.

## Related Skills
Other skills that complement this one.

DOM Hints Convention

Always provide multiple selectors in priority order:

- **DOM hints:**
  - Primary: `#add-to-cart-button`
  - Secondary: `input[name="submit.add-to-cart"]`
  - Text fallback: button containing text "Add to Cart"
  - ARIA fallback: `[aria-label="Add to Cart"]`

Wait Conditions

Be explicit:

- **Wait condition:** Element `#confirmation-text` visible within 10 seconds

Fallbacks

Always include detection + recovery:

- **Fallback:**
  - If button not found within 5s -> search for text "Add to Cart"
  - If page shows "Sign in" -> stop, report "User not logged in"
  - If CAPTCHA appears -> pause, escalate to user

Versioning

Skill Versions (Semver)

• MAJOR -- breaking changes to structure or behavior
• MINOR -- new features/steps without breaking existing flow
• PATCH -- bug fixes (updated selectors, typo fixes)

Schema Versions

• 1.0 -- initial release (this document)
• 1.1 -- additive changes only (new optional fields), all 1.0 skills remain valid
• 2.0 -- breaking changes with migration guide

Auto-Deprecation

Skills are flagged for review when:

• target.last_verified is more than 90 days old
• Success rate drops below 30% over 50+ executions
• 3+ community reports
• Target domain becomes unreachable

Creators get a 30-day notice to update before the skill is suspended.