groove-dev 0.13.0 → 0.14.0

package/docs/SKILLS-API-SPEC.md

@@ -0,0 +1,277 @@
+# Skills Marketplace API — Build Spec
+
+> Instructions for building the server-side Skills API that powers the GROOVE Skills Store.
+> This API is hosted on the docs/retail site (docs.groovedev.ai).
+
+## Context
+
+GROOVE is an agent orchestration tool. Its GUI has a Skills Store (app-store style) that currently reads from a static `registry.json` file. We need a real API so users can **submit, edit, and sell** their own skills. The GROOVE daemon will fetch from this API instead of the static file.
+
+### What exists today (static files):
+- `https://docs.groovedev.ai/skills/registry.json` — JSON array of all skill metadata
+- `https://docs.groovedev.ai/skills/content/<id>.md` — individual SKILL.md files
+
+### What we're building:
+A REST API that replaces the static files and adds CRUD + author management.
+
+---
+
+## Data Model
+
+### Skill
+
+```json
+{
+  "id": "frontend-design",
+  "name": "Frontend Design",
+  "description": "Create distinctive, production-grade frontend interfaces...",
+  "author": "Anthropic",
+  "authorId": "user_abc123",
+  "authorProfile": {
+    "avatar": "https://...",
+    "website": "https://anthropic.com",
+    "github": "anthropics",
+    "twitter": "AnthropicAI",
+    "bio": "Building reliable AI systems"
+  },
+  "category": "design",
+  "tags": ["frontend", "ui", "css", "react"],
+  "roles": ["frontend", "fullstack"],
+  "source": "claude-official",
+  "icon": "P",
+  "contentUrl": "https://docs.groovedev.ai/skills/content/frontend-design.md",
+  "content": "--- (full SKILL.md content) ---",
+  "downloads": 1840,
+  "rating": 4.8,
+  "ratingCount": 124,
+  "price": 0,
+  "featured": false,
+  "status": "published",
+  "version": "1.0.0",
+  "createdAt": "2026-04-01T00:00:00Z",
+  "updatedAt": "2026-04-06T00:00:00Z"
+}
+```
+
+**Categories** (enum): `design`, `quality`, `devtools`, `workflow`, `security`, `specialized`
+
+**Status** (enum): `draft`, `review`, `published`, `rejected`, `unlisted`
+
+**Source**: `claude-official` for Anthropic skills, `community` for user-submitted
+
+### Author / User
+
+```json
+{
+  "id": "user_abc123",
+  "githubId": "12345",
+  "username": "johndoe",
+  "displayName": "John Doe",
+  "avatar": "https://avatars.githubusercontent.com/u/12345",
+  "bio": "Senior UI designer, 10 years experience",
+  "website": "https://johndoe.dev",
+  "github": "johndoe",
+  "twitter": "johndoe",
+  "portfolio": "https://dribbble.com/johndoe",
+  "createdAt": "2026-04-01T00:00:00Z",
+  "skillCount": 3,
+  "totalDownloads": 5200
+}
+```
+
+---
+
+## API Endpoints
+
+Base URL: `https://docs.groovedev.ai/api/v1`
+
+### Public (no auth)
+
+#### `GET /skills`
+Returns the full skill registry. This is what the GROOVE daemon fetches on startup.
+
+Query params:
+- `search` — text search on name, description, tags
+- `category` — filter by category
+- `sort` — `popular` (default), `rating`, `newest`, `name`
+- `status` — defaults to `published` only
+- `author` — filter by authorId
+- `limit` — pagination (default 50)
+- `offset` — pagination offset
+
+Response:
+```json
+{
+  "skills": [ ... ],
+  "total": 21,
+  "categories": [
+    { "id": "devtools", "count": 9 },
+    { "id": "quality", "count": 3 }
+  ]
+}
+```
+
+**Important:** The response shape must match what the GROOVE daemon expects. The `skills` array uses the same schema as `registry.json` today. The `content` field should NOT be included in list responses (it's large). Only metadata.
+
+#### `GET /skills/:id`
+Returns a single skill with full metadata.
+
+Response: single skill object (without `content` field)
+
+#### `GET /skills/:id/content`
+Returns the full SKILL.md content for a skill.
+
+Response:
+```json
+{
+  "id": "frontend-design",
+  "content": "---\nname: Frontend Design\n---\n\n..."
+}
+```
+
+#### `GET /skills/registry.json`
+**Backwards compatibility.** Returns the same format as the current static file so older GROOVE versions still work. Just the skills array, no wrapper object.
+
+#### `GET /authors/:id`
+Public author profile.
+
+Response: author object + their published skills
+
+---
+
+### Authenticated (requires GitHub OAuth token)
+
+#### Auth Flow
+- GitHub OAuth (standard web flow)
+- User authorizes, we get GitHub profile
+- Create or update user record
+- Return JWT for subsequent API calls
+- GROOVE daemon does NOT handle auth — this is for the web portal / submission flow
+
+#### `POST /skills`
+Submit a new skill.
+
+Body:
+```json
+{
+  "name": "My Awesome Skill",
+  "description": "Does amazing things...",
+  "category": "design",
+  "tags": ["ui", "css"],
+  "roles": ["frontend"],
+  "icon": "A",
+  "content": "---\nname: My Awesome Skill\n---\n\nFull SKILL.md content here...",
+  "price": 0,
+  "version": "1.0.0"
+}
+```
+
+- `id` is auto-generated from slugified `name`
+- `author`, `authorId`, `authorProfile` populated from authenticated user
+- `source` set to `community`
+- `status` set to `draft` initially
+- `downloads`, `rating`, `ratingCount` initialized to 0
+
+Response: created skill object
+
+#### `PUT /skills/:id`
+Edit an existing skill. Author-only.
+
+Body: partial skill object (only changed fields)
+
+Restrictions:
+- Can only edit your own skills
+- Cannot change `id`, `authorId`, `source`, `downloads`, `rating`, `ratingCount`
+- Changing `content` bumps `updatedAt`
+
+#### `DELETE /skills/:id`
+Remove a skill. Author-only. Sets status to `unlisted` (soft delete).
+
+#### `POST /skills/:id/publish`
+Submit a skill for review / publish it.
+- If `price === 0`: auto-publish (set status to `published`)
+- If `price > 0`: set status to `review` (manual review before listing)
+
+#### `PUT /authors/me`
+Update your own author profile.
+
+Body:
+```json
+{
+  "displayName": "John Doe",
+  "bio": "Senior UI designer",
+  "website": "https://...",
+  "twitter": "johndoe",
+  "portfolio": "https://..."
+}
+```
+
+---
+
+### Future (Payments — don't build yet, but design schema for it)
+
+- `POST /skills/:id/purchase` — record a purchase
+- `GET /authors/me/earnings` — seller dashboard
+- Stripe Connect for payouts
+- 80/20 revenue share (creator/platform)
+- Price field already in the skill model, just not enforced yet
+
+---
+
+## Key Design Decisions
+
+1. **Backwards compatible** — `/skills/registry.json` must keep working as a plain JSON array. The GROOVE daemon currently fetches this on startup. Newer daemon versions will switch to `/api/v1/skills`.
+
+2. **Content separate from metadata** — The `content` (full SKILL.md) is large. Never include it in list/registry responses. Only serve it via `/skills/:id/content`.
+
+3. **Soft deletes** — Never hard-delete skills. Set status to `unlisted`.
+
+4. **Download counting** — Increment on install. The GROOVE daemon will POST to `/skills/:id/install` to record an install (new endpoint, unauthenticated, rate-limited by IP).
+
+5. **Rating** — Not building the rating/review system yet, but the fields are in the schema. We'll add `POST /skills/:id/rate` later.
+
+6. **The 21 Anthropic skills** — Seed the database with these. They have `source: "claude-official"` and `author: "Anthropic"`. They should not be editable via the API.
+
+7. **Validation:**
+   - `name`: 3-100 chars
+   - `description`: 10-500 chars
+   - `content`: must be valid markdown, max 50KB
+   - `category`: must be one of the enum values
+   - `tags`: max 10, each 2-30 chars
+   - `icon`: single character
+   - `price`: >= 0, max 99.99
+
+---
+
+## Tech Recommendations
+
+- Whatever fits the existing docs site stack
+- If starting fresh: Node.js + Express or Hono, SQLite or Postgres
+- GitHub OAuth for auth
+- JWT for session tokens
+- Rate limiting on public endpoints (60/min per IP)
+- CORS: allow `localhost:*` (for GROOVE daemon) + `groovedev.ai` origins
+
+---
+
+## Install Tracking Endpoint
+
+Add this for download counting (the GROOVE daemon calls this when a user installs a skill):
+
+#### `POST /skills/:id/install`
+Unauthenticated. Rate-limited (1 per skill per IP per hour).
+
+Increments the `downloads` counter.
+
+Response: `{ "downloads": 1841 }`
+
+This replaces the current flow where the daemon downloads from `contentUrl` directly. New flow:
+1. Daemon calls `POST /api/v1/skills/:id/install` to record the install
+2. Daemon calls `GET /api/v1/skills/:id/content` to get the SKILL.md
+3. Daemon saves locally
+
+---
+
+## Seed Data
+
+The current `skills-registry.json` in the GROOVE repo has all 21 Anthropic skills with full metadata including downloads, ratings, prices, author profiles, and featured flags. Use this to seed the database.