# Agent Skill Specification v1.2

This document defines the canonical repository and public JSON format for skills in the Agent Skill Exchange.

## Overview

A skill is a directory containing a `SKILL.md` file. The file has two parts:

1. **YAML frontmatter** — structured metadata between `---` delimiters
2. **Markdown body** — human-readable description and install instructions

## Directory Structure

```text
skills/
  <slug>/
    SKILL.md        # Required — skill definition
    references/     # Optional — supporting files
    scripts/        # Optional — automation scripts
```

The `<slug>` is a URL-safe identifier: lowercase, hyphens instead of spaces, no special characters. It must match the skill directory name.

## Canonical Frontmatter Schema

```yaml
---
name: string           # Required — human-readable display name
slug: string           # Required — stable URL/path/install identifier, matching skills/<slug>/
description: string    # Required — what the skill does and when to use it
category: string       # Required — one of the valid categories
framework: string      # Required — primary framework
verification: string   # Required — listed or security_reviewed
source: string         # Optional — upstream repo, documentation, package, or canonical source URL
github_stars: number   # Optional — top-level compatibility signal when available
tool_ecosystem:        # Optional — only if backed by a real tool with verified signals
  tool: string
  github_repo: string
  github_stars: number
  npm_package: string
  npm_weekly_downloads: number
  license: string
  maintained: boolean
---
```

### Compatibility aliases

- `name` is canonical for human-readable display text.
- `slug` is canonical for URL, directory, install, and machine identity.
- `title` is deprecated. During the transition, validators may allow it only when it exactly equals `name`; generators must not emit `title` in new repository frontmatter.
- `verification` is canonical for public files. WordPress may keep internal `verification_status` metadata, but exports must normalize it to the public values below.

## Field Definitions

### `name` (required, string)

The human-readable display name of the skill. Should be concise and descriptive.

**Examples**: `"Stripe Webhook Verifier"`, `"GitHub Actions Workflow Generator"`

### `slug` (required, string)

The stable URL-safe identifier. It must match the containing directory name under `skills/`.

### `description` (required, string)

A one-paragraph description of what the skill does and when to use it. It should reference specific APIs, tools, or techniques. Avoid vague language.

**Good**: `"Verifies Stripe webhook payload signatures using HMAC-SHA256 to prevent replay attacks and forged events."`

**Bad**: `"A helpful tool for working with Stripe."`

### `category` (required, string)

One of the 17 valid categories. Must match exactly.

| Category | Description |
|----------|-------------|
| Browser Automation | Navigation, login flows, form handling, screenshots |
| Calendar, Email & Productivity | Calendar, email, scheduling, productivity tools |
| CI/CD Integrations | Pipelines, workflows, deployment, CI templates |
| Code Quality & Review | Linters, reviewers, test generators, coverage |
| Content Writing & SEO | SEO, content generation, editorial workflows |
| Data Extraction & Transformation | Schema validation, ETL, data mapping, conversion |
| Developer Tools | Coding agents, repo tools, scaffolders, terminal |
| Image & Creative Automation | Image generation, editing, design automation |
| Integrations & Connectors | Third-party connectors, webhooks, API bridges |
| Library & API Reference | SDK docs, API parsers, symbol resolvers |
| Media & Transcription | Audio transcription, video processing, media tools |
| Monitoring & Alerts | Error tracking, uptime, alerting, observability |
| Research & Scraping | Web research, content discovery, data collection |
| Runbooks & Diagnostics | Incident response, diagnostics, troubleshooting |
| Security & Verification | Vulnerability scanning, signature verification |
| Templates & Workflows | Scaffolders, boilerplate generators, automation |
| WordPress & CMS | WordPress, theme/plugin dev, WP-CLI automation, CMS management |

### `framework` (required, string)

The primary framework this skill targets. Valid values:

- `Claude Code`
- `Claude Agents`
- `ChatGPT Agents`
- `Codex`
- `Cursor`
- `Custom Agents`
- `Gemini`
- `Google Workspace`
- `MCP`
- `Multi-Framework`
- `OpenClaw`
- `WordPress`

### `verification` (required, string)

The public trust tier of the skill.

| Value | Meaning |
|-------|---------|
| `listed` | Published — backed by a real tool, repo, package, or documented workflow |
| `security_reviewed` | Content scanned for malicious patterns, prompt injection, and unsafe instructions |

New skills enter as `listed`. Security review is handled by the marketplace team in batches.

### Internal WordPress verification mapping

WordPress may store older/internal values in `verification_status`. Public repo files and JSON indexes must normalize them as:

| Internal value | Public `verification` |
|----------------|------------------------|
| missing / empty | `listed` |
| `listed` | `listed` |
| `verified_metadata` | `listed` |
| `security_reviewed` | `security_reviewed` |

Do not expose `verified_metadata` as a separate public tier.

### `source` (optional, string)

The upstream repo, documentation, package, or canonical source URL that backs the skill. Prefer the original upstream source over the Agent Skill Exchange listing URL when both are available.

### `tool_ecosystem` (optional, object)

Only include if the skill is backed by a real tool with verifiable signals. All sub-fields are optional; include only values with real provenance.

## Canonical Public Catalog JSON

`skills.json` should use the same public naming as frontmatter. During one transition cycle, JSON endpoints may also emit `title` with the same value as `name` for backward compatibility:

```json
{
  "slug": "playwright-mcp-browser-automation",
  "name": "Playwright MCP Browser Automation",
  "title": "Playwright MCP Browser Automation",
  "description": "Official Playwright-powered browser control for agent workflows.",
  "category": ["Browser Automation"],
  "framework": ["Claude Code", "Cursor", "MCP", "OpenClaw"],
  "verification": "security_reviewed",
  "signals": {
    "tool": "playwright",
    "github_stars": 84874,
    "npm_weekly_downloads": 39806814,
    "license": "Apache-2.0"
  }
}
```

## Public Agent Endpoints

The public site exposes static, cacheable agent-readable endpoints generated from the same canonical catalog output:

- `https://agentskillexchange.com/skills.json` — full canonical catalog JSON
- `https://agentskillexchange.com/openclaw.json` — OpenClaw-oriented manifest with install guidance and catalog links
- `https://agentskillexchange.com/codex.json` — Codex-oriented manifest with repository/path/schema guidance
- `https://agentskillexchange.com/llms.txt` — concise agent/human discovery document

Endpoint requirements:

1. JSON endpoints must return `Content-Type: application/json`.
2. `llms.txt` must return `Content-Type: text/plain`.
3. Endpoints must be public, unauthenticated, and cacheable.
4. Endpoint schema must use `name` for display and `slug` for identity. `title` may appear only as a transition alias equal to `name`; internal fields such as `verification_status` or `verified_metadata` must never be exposed.
5. Endpoint health is checked by `python3 scripts/smoke-agent-endpoints.py --base https://agentskillexchange.com`.

## Markdown Body

The body follows the frontmatter and contains:

1. **Name** — H1 heading matching the skill display name
2. **Description** — One or more paragraphs explaining the skill
3. **Installation** — Commands or setup notes for supported agents

### Example

~~~markdown
---
name: Stripe Webhook Signature Verifier
slug: stripe-webhook-signature-verifier
description: Verifies Stripe webhook payload signatures using HMAC-SHA256 to prevent replay attacks and forged events.
category: Security & Verification
framework: Custom Agents
verification: listed
source: https://docs.stripe.com/webhooks/signature
---
# Stripe Webhook Signature Verifier

Verifies Stripe webhook payload signatures using HMAC-SHA256 to prevent
replay attacks and forged events. Supports both test and live mode keys.

## Installation

```bash
clawhub install stripe-webhook-signature-verifier
```
~~~

## Validation Rules

A valid `SKILL.md` must pass the committed parser-backed validator:

```bash
python3 scripts/validate_skills.py --all
```

The validator must:

1. Parse YAML frontmatter with a real YAML parser, not grep/sed
2. Reject duplicate YAML keys
3. Include all required fields (`name`, `slug`, `description`, `category`, `framework`, `verification`)
4. Validate required field types; canonical public fields are scalar strings unless explicitly documented otherwise
5. Allow deprecated `title` only as a temporary alias when it exactly equals `name`; reject `verification_status` and `verified_metadata`
6. Use a lowercase kebab-case `slug` matching the containing directory name
7. Use a valid category from the public category set; transitional generated buckets such as `General` and `Uncategorized` may be allowed only while the live taxonomy backlog is being cleaned
8. Use a valid framework from the public framework set
9. Use a valid public verification tier (`listed` or `security_reviewed`)
10. Validate `source` as an HTTP(S) URL when present
11. Validate numeric signal fields as numbers, not strings
12. Validate `tool_ecosystem` as an object with typed optional fields
13. Have a markdown body with an H1 heading and enough useful content
14. Emit GitHub Actions annotations in CI

## Versioning

This spec follows semantic versioning. The current version is **1.2**.

Changes to required fields or validation rules increment the major version. New optional fields increment the minor version.