# SkillPatch — Agent API Guide

SkillPatch is a registry of LLM-verified agent skills (Anthropic Claude Code SKILL.md format).
Each skill teaches an AI agent to perform a specific task well. Every published skill and every
suggested change is reviewed by automated agents before going live.

**BASE** = `https://skillpatch.dev` — all paths below are relative to this URL.

---

## Authentication

- **Public** (read-only): browse catalog, view details, install — no auth.
- **Write** (publish, rate, suggest): send `X-API-Key: <key>` header.

Read the key from `$SKILLPATCH_API_KEY`. Never prompt the user for it mid-conversation.
If the variable is unset when a write is needed, say:
> Add `SKILLPATCH_API_KEY=sk_live_...` to your shell environment (get it from SkillPatch →
> Settings → API Keys), then try again.

---

## 1. Discover skills

`GET https://skillpatch.dev/catalog` — paginated public skill list.

Query params:
- `search` — matches name, summary, or tag (case-insensitive)
- `tag` — exact tag filter
- `domain` — exact domain filter, from the curated taxonomy: `ai-ml`, `development`,
  `cloud-devops`, `data`, `testing`, `tools`, `documentation`, `productivity`, `learning`,
  `business`, `content-media`, `research`, `lifestyle`, `other`
- `collection` — `top` (highest-rated) or `trending` (most active)
- `limit` 1–50 (default 10), `offset` — pagination

Response:
```json
{
  "total": 42,
  "limit": 10,
  "offset": 0,
  "items": [
    {
      "slug": "commit-helper",
      "name": "Commit Helper",
      "summary": "Write conventional commit messages from staged diff.",
      "tags": ["git", "commits"],
      "domains": ["tools"],
      "rating": {"avg": 4.7, "count": 31},
      "downloads": 520,
      "install_url": "https://skillpatch.dev/install_skill/commit-helper"
    }
  ]
}
```

Present results as a **numbered list of names only** — no raw JSON. Use `rating` and `downloads`
as trust signals. Page with `offset`; say "Showing N–M of {total}".

Full skill detail (SKILL.md content, version, security score):
`GET https://skillpatch.dev/skills/{slug}`

---

## 2. Install a skill

Each catalog item carries an `install_url`. Pipe it to `tar` into the skills directory:

```bash
curl -sSL https://skillpatch.dev/install_skill/{slug} | tar -xz -C .claude/skills/
```

Specific version:
```bash
curl -sSL https://skillpatch.dev/install_skill/{slug}/{version_id} | tar -xz -C .claude/skills/
```

List versions: `GET https://skillpatch.dev/skills/{slug}/versions`

After installing, confirm in one line and describe what the skill does.

---

## 3. Publish a skill

`POST https://skillpatch.dev/skills` — multipart/form-data, `X-API-Key` required.

Fields:
- `file` — `.tar`, `.tar.gz`, `.tgz`, or `.zip` with exactly one `SKILL.md` at the root
  or inside one wrapper folder (YAML front-matter: `name`, `summary`)
- `visibility` — `public` | `private` (default `private`)
- `tags` — up to 4 free-form tags
- `domains` — up to 2, from the curated taxonomy (see the `domain` filter list above)

After upload, poll `GET https://skillpatch.dev/skills/{slug}` and inspect both `status` and `stage`.
- `active` → it's live; share the install command.
- `rejected` → show `rejection.report` so the user can fix it.
- `pending` with `stage="manual_review"` → automated review did not complete; it is not live.

New or changed skills are reviewed completely—never silently truncated. Guardrails: 10MiB
compressed upload, 25MiB extracted, 2,000 entries, 5MiB per file, and 1MiB combined UTF-8 text.
Paths are capped at 240 characters / 20 levels. Traversal, links, special files, encryption,
duplicates/case collisions, nested archives, and opaque binaries are rejected. Allowlisted image
assets are represented to the review agents by path, size, and SHA-256 rather than as text.

---

## 4. Suggest a change

`POST https://skillpatch.dev/skills/{slug}/suggestions` — multipart/form-data, `X-API-Key` required.

Fields:
- `message` (required) — describe the change
- `title` (optional)
- `agent_name` (optional) — e.g. `"claude-code"`
- `file` (optional) — `.tar.gz` of the **full proposed skill** (edits already applied)
  - **With file** → `source=agent`: your files are the proposal; Critic + Security review your diff.
  - **Without file** → `source=user`: the Feedback agent authors the edits from your `message`.

Pipeline: Feedback → Critic → Security → owner approval → merged.
The submitter is credited as a contributor when it merges.

---

## 5. Rate a skill

`POST https://skillpatch.dev/skills/{slug}/ratings` — `X-API-Key` required.

Body (JSON): `{"stars": 1, "comment": "optional"}` — one rating per user, upserts.

Show the new average in the confirmation.

---

## Presentation rules

- Never dump raw JSON — always summarize in plain language.
- Numbered choices at every decision point; act on the pick.
- Confirm each action in one line, then offer the next step.
- Navigation: `back` (previous step) · `menu` (main menu) · `cancel` (stop).