How to Create Your First SiteSkills Skill

February 5, 2026

You have installed the CLI, browsed the marketplace, maybe even installed a few skills. Now it is time to create your own. This tutorial walks you through building a complete SiteSkills skill from scratch, testing it locally, and publishing it to the marketplace.

We will build a skill called github-star-repo -- a simple skill that navigates to a GitHub repository page and clicks the Star button. It is straightforward enough to learn the format, but realistic enough to encounter real-world considerations like authentication, element detection, and error handling.

Prerequisites

Before you start, make sure you have:

• The SiteSkills CLI installed (npm install -g siteskills)
• A SiteSkills account (sign up at siteskills.ai)
• Authenticated via siteskills login

Step 1: Scaffold the Project

Run the interactive scaffolding command:

siteskills init

The CLI walks you through a series of prompts:

Create a new SiteSkills skill
─────────────────────────────
Skill name (slug): github-star-repo
Display name: GitHub -- Star a Repository
Target domain(s): github.com
Category: productivity
Difficulty: easy
Requires auth? (y/N): y

Created github-star-repo/
  ├── SKILL.md
  ├── siteskills.json
  ├── README.md
  └── tests/
      └── test-basic.json

You now have a skill directory with all the required files, pre-filled with sensible defaults. Let us customize each one.

Step 2: Write the Navigation Flow in SKILL.md

Open github-star-repo/SKILL.md. This is the heart of your skill -- the file that AI browser agents read at runtime. Replace the scaffolded content with the following:

---
name: github-star-repo
description: "Navigates to a GitHub repository and stars it"
triggers:
  - "star a GitHub repo"
  - "star this repository on GitHub"
  - "add a star to a GitHub repo"
---

# GitHub -- Star a Repository

## Prerequisites
- User must be logged into GitHub
- Browser viewport at least 1024x768

## Input Parameters
- `repo_url` (required): Full URL of the GitHub repository

## Navigation Flow

### Step 1: Navigate to Repository
- **Goal:** Load the target repository page
- **Action:** Navigate to the provided `repo_url`
- **Expected state:** Repository page loads with header visible
- **DOM hints:**
  - Primary: `#repository-container-header`
  - Secondary: `.AppHeader-context-full`
  - Text fallback: heading containing the repository name
- **Wait condition:** Element `#repository-container-header` visible
  within 10 seconds
- **Fallback:**
  - If 404 page -> stop, report "Repository not found"
  - If login page -> stop, report "User not logged into GitHub"

### Step 2: Locate the Star Button
- **Goal:** Find the Star/Unstar button
- **Action:** Locate the starring form in the repository header
- **Expected state:** Star button is visible and clickable
- **DOM hints:**
  - Primary: `form.js-social-form button[value="star"]`
  - Secondary: `.starring-container button`
  - Text fallback: button containing text "Star"
  - ARIA fallback: `[aria-label="Star this repository"]`
- **Wait condition:** Star button element present within 5 seconds
- **Fallback:**
  - If "Unstar" button found -> stop, report "Repository is
    already starred"
  - If no button found -> try scrolling up to page top, retry

### Step 3: Click Star
- **Goal:** Star the repository
- **Action:** Click the Star button
- **Expected state:** Button text changes to "Starred" or "Unstar"
- **DOM hints:**
  - Success indicator: `form.js-social-form button[value="unstar"]`
  - Text indicator: button text changes to include "Starred"
- **Wait condition:** Star count increments or button state changes
  within 5 seconds
- **Fallback:**
  - If button click has no effect -> wait 2 seconds, retry once
  - If error message appears -> report the error text to user

## Verification
The skill is successful when ALL of the following are true:
1. The "Unstar" button is now visible (replacing the "Star" button)
2. No error messages are displayed
3. Page URL still matches the original repository

## Anti-Detection Notes
- Insert a 1-2 second pause before clicking the Star button
- Scroll the Star button into view naturally before clicking
- Do not reload the page after starring

## Related Skills
- `github-login` -- log into GitHub if not authenticated
- `github-fork-repo` -- fork a repository

Notice the structure: every step has a clear Goal, Action, Expected state, DOM hints (with multiple selectors in priority order), a Wait condition, and Fallback instructions. This layered approach is what makes skills resilient.

Step 3: Configure the Manifest

Open github-star-repo/siteskills.json and update the key fields:

{
  "$schema": "https://siteskills.ai/schema/v1.0.json",
  "schema_version": "1.0",
  "skill": {
    "name": "github-star-repo",
    "display_name": "GitHub -- Star a Repository",
    "description": "Navigates to a GitHub repository page and clicks the Star button.",
    "version": "1.0.0",
    "author": {
      "name": "your-username",
      "display_name": "Your Display Name"
    },
    "license": "MIT",
    "created": "2026-02-05T00:00:00Z",
    "updated": "2026-02-05T00:00:00Z"
  },
  "target": {
    "domains": ["github.com"],
    "url_patterns": ["https://github.com/*/*"],
    "requires_https": true,
    "last_verified": "2026-02-05T00:00:00Z",
    "verified_by": "manual"
  },
  "compatibility": {
    "agents": [
      { "name": "claude-cowork", "min_version": null, "notes": "Tested" },
      { "name": "browser-use", "min_version": "0.3.0", "notes": "Requires Playwright" },
      { "name": "stagehand", "min_version": "3.0.0", "notes": "Tested" }
    ],
    "requires_auth": true,
    "auth_type": "session",
    "auth_notes": "User must be logged into GitHub.",
    "requires_captcha_solver": false,
    "requires_proxy": false,
    "requires_cookies": true,
    "requires_javascript": true
  },
  "navigation": {
    "total_steps": 3,
    "estimated_actions": 3,
    "estimated_time_seconds": 8,
    "difficulty": "easy",
    "interaction_types": ["click", "wait_for_element", "verify_text"],
    "failure_modes": [
      {
        "id": "already-starred",
        "description": "Repository is already starred by the user",
        "detection": "Button text is 'Unstar' instead of 'Star'",
        "recovery": "Report to user that repo is already starred",
        "probability": "medium"
      },
      {
        "id": "not-logged-in",
        "description": "User is not authenticated on GitHub",
        "detection": "Redirect to login page or Sign In prompt visible",
        "recovery": "Stop and report authentication required",
        "probability": "low"
      }
    ]
  },
  "categories": ["productivity"],
  "tags": ["github", "star", "repository", "social"],
  "pricing": { "model": "free", "price_usd": null }
}

The manifest is what the SiteSkills platform indexes. It tells the marketplace what your skill does, which agents it works with, what can go wrong, and how the skill handles failures.

Step 4: Test Locally

Before publishing, validate your skill with the built-in checker:

siteskills validate ./github-star-repo/

You should see output like:

Validating github-star-repo...

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

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

Result: PASS (ready to publish)

Next, test with a real agent. Install the skill into your agent's skills directory and try triggering it:

# For Claude Cowork
cp -r ./github-star-repo/ .claude/skills/github-star-repo/

# Then ask your agent: "Star the repository at github.com/siteskills/siteskills-cli"

Watch the agent work through each step. If it struggles with a selector, update the DOM hints. If it misses an edge case, add a fallback. This iterative testing is what separates a good skill from a great one.

Step 5: Publish

Once you are satisfied with local testing, publish to the marketplace:

siteskills publish ./github-star-repo/

Publishing github-star-repo v1.0.0...

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

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

Your skill now enters the automated security scanning pipeline. The scanner runs static analysis, permission analysis, and content analysis. Skills scoring 80 or above are auto-approved and appear on the marketplace immediately. Lower scores go to manual review -- you will receive an email either way.

Tips for Your First Skill

Start simple. A 3-step skill that works every time beats a 15-step skill that breaks on step 8. You can always add complexity in later versions.

Provide multiple DOM selectors. Websites change layouts frequently. If you only provide one CSS selector and the site redesigns, your skill breaks. Always include an ID, a class, a text fallback, and an ARIA label when possible.

Document your failure modes honestly. The scanner checks that your declared failure modes are realistic. And users appreciate knowing what can go wrong before they run the skill.

Test with multiple agents. A skill might work perfectly with Claude Cowork but trip up in Browser Use because of timing differences. Test with every agent you declare in the compatibility section.

Set last_verified to today. This field drives the auto-deprecation system. Skills that have not been verified in 90 days get flagged for review. Keep it current and your skill stays active.

What Happens Next

After your skill is approved, it appears on the marketplace at siteskills.ai/skills/github-star-repo. Users can find it by searching, install it with siteskills install github-star-repo, and start using it immediately.

You will see download counts, success rates, and user reviews on your creator dashboard. Use this feedback to iterate -- bump the version, update selectors, add failure modes, and re-publish.

Ready to build? Run siteskills init and make something useful.