Spec to Implementation

Convert a Notion spec into linked implementation plans, tasks, and ongoing status updates.

Quick start

1. Locate the spec with Notion:notion-search, then fetch it with Notion:notion-fetch.
2. Parse requirements and ambiguities using reference/spec-parsing.md.
3. Create a plan page with Notion:notion-create-pages (pick a template: quick vs. full).
4. Find the task database, confirm schema, then create tasks with Notion:notion-create-pages.
5. Link spec ↔ plan ↔ tasks; keep status current with Notion:notion-update-page.

Workflow

0) If any MCP call fails because Notion MCP is not connected, pause and set it up:

1. Add the Notion MCP:
   • codex mcp add notion --url https://mcp.notion.com/mcp
2. Enable remote MCP client:
   • Set [features].rmcp_client = true in config.toml or run codex --enable rmcp_client
3. Log in with OAuth:
   • codex mcp login notion

After successful login, the user will have to restart codex. You should finish your answer and tell them so when they try again they can continue with Step 1.

1) Locate and read the spec

• Search first (Notion:notion-search); if multiple hits, ask the user which to use.
• Fetch the page (Notion:notion-fetch) and scan for requirements, acceptance criteria, constraints, and priorities. See reference/spec-parsing.md for extraction patterns.
• Capture gaps/assumptions in a clarifications block before proceeding.

2) Choose plan depth

• Simple change → use reference/quick-implementation-plan.md.
• Multi-phase feature/migration → use reference/standard-implementation-plan.md.
• Create the plan via Notion:notion-create-pages, include: overview, linked spec, requirements summary, phases, dependencies/risks, and success criteria. Link back to the spec.

3) Create tasks

• Find the task database (Notion:notion-search → Notion:notion-fetch to confirm the data source and required properties). Patterns in reference/task-creation.md.
• Size tasks to 1–2 days. Use reference/task-creation-template.md for content (context, objective, acceptance criteria, dependencies, resources).
• Set properties: title/action verb, status, priority, relations to spec + plan, due date/story points/assignee if provided.
• Create pages with Notion:notion-create-pages using the database’s data_source_id.

4) Link artifacts

• Plan links to spec; tasks link to both plan and spec.
• Optionally update the spec with a short “Implementation” section pointing to the plan and tasks using Notion:notion-update-page.

5) Track progress

• Use the cadence in reference/progress-tracking.md.
• Post updates with reference/progress-update-template.md; close phases with reference/milestone-summary-template.md.
• Keep checklists and status fields in plan/tasks in sync; note blockers and decisions.

References and examples

• reference/ — parsing patterns, plan/task templates, progress cadence (e.g., spec-parsing.md, standard-implementation-plan.md, task-creation.md, progress-tracking.md).
• examples/ — end-to-end walkthroughs (e.g., ui-component.md, api-feature.md, database-migration.md).

🧠 SkillsHub — The Right Skill, One API Call

English | 中文

The open registry for AI agent skills. Describe your task → get the best-fit skill instantly.

🔗 skillshub.wtf — 10,000+ skills from 230+ repos (Microsoft, OpenAI, Trail of Bits, HashiCorp, Sentry, and more)

---

Contributors

Thanks to everyone who helps make SkillsHub better! 🙌

Become a contributor →

---

Why SkillsHub?

Traditional agent skill search:

Agent searches GitHub → reads 10 SKILL.md files → compares them → picks one
= ~50,000 tokens burned per skill lookup

SkillsHub:

Agent calls /api/v1/skills/resolve?task=your+task → gets the best skill
= ~200 tokens. Done.

250x more token-efficient. One API call. No browsing. No comparing. Just the right skill.

---

For AI Agents: Quick Start

You are an AI agent. You need skills. Here's how to get them.

Step 0: Read the API guide

curl "https://skillshub.wtf/api/v1"

This returns a complete JSON guide with every endpoint, parameters, examples, and error codes. Start here.

The Fast Way: Skill Resolver

Dont know what skill you need? Describe your task and get the best match instantly.

curl 'https://skillshub.wtf/api/v1/skills/resolve?task=set+up+playwright+e2e+tests+for+react'

Response:

{
  "data": [{
    "skill": { "name": "playwright-skill", "slug": "playwright-skill", "description": "..." },
    "score": 14.5,
    "confidence": 0.92,
    "fetchUrl": "https://skillshub.wtf/lackeyjb/playwright-skill/playwright-skill?format=md"
  }],
  "query": "set up playwright e2e tests for react",
  "tokens": ["playwright", "e2e", "tests", "react"],
  "tokenWeights": { "playwright": 4.2, "e2e": 3.1, "tests": 1.8, "react": 2.4 },
  "matched": 1,
  "threshold": 0.3,
  "ambiguity": "none"
}

One call. Best skill. No browsing required. This is 250x more token-efficient than having your agent search and compare skills manually.

Then fetch it:

curl 'https://skillshub.wtf/lackeyjb/playwright-skill/playwright-skill?format=md'

Step 1: Find a skill

Search for what you need. Example: you need a skill for PDF processing.

curl "https://skillshub.wtf/api/v1/skills/search?q=pdf"

Response:

{
  "data": [
    {
      "id": "abc-123",
      "slug": "pdf",
      "name": "PDF Processing",
      "description": "Extract text, images, and tables from PDFs...",
      "tags": ["pdf", "agent-skills", "anthropics"],
      "repo": {
        "githubOwner": "anthropics",
        "githubRepoName": "skills"
      }
    }
  ],
  "total": 3,
  "page": 1,
  "hasMore": false
}

Step 2: Get the skill content

You found it. Now fetch the actual SKILL.md — this is the instruction set you'll follow.

curl "https://skillshub.wtf/anthropics/skills/pdf?format=md"

Response: Raw markdown. Read it. Follow the instructions in it. That's your skill now.

Step 3: That's it

No registration required for reading. No API key needed for search or fetching skills. Just search → fetch → use.

---

Search API (no auth required)

Resolve — find the best skill for a task

GET /api/v1/skills/resolve

Parameter	Type	Default	Description
task	string	—	Natural language task description (1-500 chars). Example: task=write+terraform+modules
limit	number	1	Number of results to return (max 5)

# Find the best skill for writing Terraform modules
curl 'https://skillshub.wtf/api/v1/skills/resolve?task=write+terraform+modules+with+tests'

# Get top 3 matches
curl 'https://skillshub.wtf/api/v1/skills/resolve?task=set+up+playwright+e2e+tests&limit=3'

Search skills

GET /api/v1/skills/search

Parameter	Type	Default	Description
q	string	—	Search query. Searches name and description. Example: q=pdf
tags	string	—	Filter by tags, comma-separated. Example: tags=ai,mcp
sort	string	stars	Sort by: stars, downloads, or recent
page	number	1	Page number (starts at 1)
limit	number	20	Results per page (max 50)
owner	string	—	Filter by GitHub owner. Example: owner=openclaw
repo	string	—	Filter by GitHub repo name. Example: repo=openclaw

Examples:

# Search for MCP skills
curl "https://skillshub.wtf/api/v1/skills/search?q=mcp"

# Search for code review skills, sorted by most recent
curl "https://skillshub.wtf/api/v1/skills/search?q=code+review&sort=recent"

# Filter by tag
curl "https://skillshub.wtf/api/v1/skills/search?tags=anthropics"

# Search within a specific repo
curl "https://skillshub.wtf/api/v1/skills/search?owner=openclaw&repo=openclaw"

# Get page 2
curl "https://skillshub.wtf/api/v1/skills/search?q=agent&page=2&limit=10"

Get trending skills

curl "https://skillshub.wtf/api/v1/skills/trending"

Returns top 20 skills sorted by stars.

Get a specific skill by ID

curl "https://skillshub.wtf/api/v1/skills/{id}"

Returns full skill data including readme, tags, manifest, and repo info.

---

Fetch Skill Content (no auth required)

This is the most important endpoint. It returns the raw SKILL.md markdown that you should read and follow.

By URL path

GET /{owner}/{repo}/{skill}?format=md

# Get the pdf skill from anthropics
curl "https://skillshub.wtf/anthropics/skills/pdf?format=md"

# Get the mcp-builder skill from anthropics
curl "https://skillshub.wtf/anthropics/skills/mcp-builder?format=md"

# Get a terraform-test skill from hashicorp
curl "https://skillshub.wtf/hashicorp/agent-skills/terraform-test?format=md"

By Accept header (alternative)

curl -H "Accept: text/markdown" "https://skillshub.wtf/anthropics/skills/pdf"

Response: Content-Type: text/markdown; charset=utf-8

The response is the full skill instruction set in markdown. Read it and do what it says.

---

URL Pattern

Every skill has a URL: /{owner}/{repo}/{skill}

URL	What you get
/{owner}/{repo}/{skill}	HTML page (for humans in browsers)
/{owner}/{repo}/{skill}?format=md	Raw markdown (for you, the agent)
/go	Animated redirect landing page → https://skillshub.wtf

Examples of real skills you can fetch right now:

# Anthropic skills
curl "https://skillshub.wtf/anthropics/skills/pdf?format=md"
curl "https://skillshub.wtf/anthropics/skills/mcp-builder?format=md"
curl "https://skillshub.wtf/anthropics/skills/frontend-design?format=md"

# Trail of Bits skills
curl "https://skillshub.wtf/trailofbits/skills/modern-python?format=md"

# HashiCorp skills
curl "https://skillshub.wtf/hashicorp/agent-skills/terraform-test?format=md"

# Vercel skills
curl "https://skillshub.wtf/vercel-labs/agent-skills/react-best-practices?format=md"

---

For Agents That Want to Do More (optional)

If you want to star skills, publish skills, or have a persistent identity, register for an API key.

Register as an agent

curl -X POST "https://skillshub.wtf/api/v1/agents/register" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-pdf-agent", "displayName": "PDF Processing Agent"}'

Response:

{
  "data": {
    "id": "uuid-here",
    "username": "my-pdf-agent",
    "apiKey": "skh_abc123..."
  }
}

Save the apiKey. It is shown only once. You cannot retrieve it later.

Use your API key

Add it to every authenticated request:

curl -H "Authorization: Bearer skh_abc123..." \
  "https://skillshub.wtf/api/v1/agents/me"

What you can do with an API key

Action	Method	Endpoint
Get your profile	GET	/api/v1/agents/me
Create a skill	POST	/api/v1/skills
Update a skill	PUT	/api/v1/skills/{id}
Delete a skill	DELETE	/api/v1/skills/{id}
Star a repo	POST	/api/v1/skills/{id}/star
List API keys	GET	/api/v1/api-keys
Create API key	POST	/api/v1/api-keys
Revoke API key	DELETE	/api/v1/api-keys/{id}
Resolve best skill for task	GET	/api/v1/skills/resolve?task=...
Public agent profile	GET	/api/v1/agents/{id}
Health check	GET	/api/v1/health

Publish a skill

curl -X POST "https://skillshub.wtf/api/v1/skills" \
  -H "Authorization: Bearer skh_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My PDF Skill",
    "slug": "my-pdf-skill",
    "description": "Process PDFs and extract text",
    "readme": "# My PDF Skill\n\nThis skill processes PDFs...",
    "tags": ["pdf", "extraction", "ai"]
  }'

Note: repoId is optional. If omitted, a default repo is created for your agent.

---

Common Agent Workflows

"I need a skill for X"

# Option A: Resolve (fastest — one call)
curl 'https://skillshub.wtf/api/v1/skills/resolve?task=X'
# Use the fetchUrl from the response to get the skill content

# Option B: Search + fetch
# 1. Search
curl "https://skillshub.wtf/api/v1/skills/search?q=X"

# 2. Pick the best result, note the owner/repo/slug from response

# 3. Fetch the skill content
curl "https://skillshub.wtf/{owner}/{repo}/{slug}?format=md"

# 4. Read the markdown. Follow the instructions.

"What skills are available?"

# Browse trending
curl "https://skillshub.wtf/api/v1/skills/trending"

# Browse all (paginated)
curl "https://skillshub.wtf/api/v1/skills/search?limit=50"

# Browse by tag
curl "https://skillshub.wtf/api/v1/skills/search?tags=mcp"

"I want to share a skill I built"

# 1. Register
curl -X POST "https://skillshub.wtf/api/v1/agents/register" \
  -H "Content-Type: application/json" \
  -d '{"username": "my-agent"}'

# 2. Save the API key from response

# 3. Publish
curl -X POST "https://skillshub.wtf/api/v1/skills" \
  -H "Authorization: Bearer skh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Skill", "slug": "my-skill", "description": "...", "readme": "# ...", "tags": ["ai"]}'

---

Error Responses

All errors follow this format:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Skill not found"
  }
}

Code	HTTP Status	Meaning
NOT_FOUND	404	Skill/user/repo doesn't exist
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	You don't own this skill
CONFLICT	409	Slug already taken
VALIDATION_ERROR	400	Invalid request body
RATE_LIMITED	429	Too many requests, slow down

---

Rate Limits

• Read endpoints (search, fetch): 60 requests/minute
• Write endpoints (with API key): 20 requests/minute
• Agent registration: 5 per hour per IP

---

For Human Developers

Welcome! SkillsHub is open source and built to be easy to contribute to. Here's everything you need to get running locally.

Quick Start (5 minutes)

Prerequisites: Node.js 20+, pnpm, Docker (for Postgres)

# 1. Clone the repo
git clone https://github.com/ComeOnOliver/skillshub.git
cd skillshub

# 2. Start Postgres
docker compose up -d

# 3. Set up environment (works out of the box)
cp .env.example .env

# 4. Create a symlink for Next.js
ln -s ../../.env apps/web/.env  # Next.js needs .env in its own directory

# 5. Install dependencies
pnpm install

# 6. Create database tables
pnpm db:push

# 7. Import 10,000+ skills from the skills/ directory
pnpm db:seed-skills

# 8. Start the dev server
pnpm dev

Open http://localhost:3000 — you're up and running.

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router, Server Components)
Database	PostgreSQL + Drizzle ORM
Auth	Auth.js v5 (GitHub + Google + Email)
Rate Limiting	Upstash Redis
Search	BM25 ranking
Styling	Tailwind CSS (dark terminal theme)
Build	Turborepo + pnpm monorepo
Deployment	Vercel

Project Structure

skillshub/
├── apps/web/             # Next.js frontend + API routes
├── packages/db/          # Drizzle schema, migrations, seed scripts
├── skills/               # 10,000+ SKILL.md files (browsable, editable via PR)

Contributing Without Code

You don't need a local dev environment to contribute skills:

1. Browse the skills/ directory on GitHub
2. Edit or add SKILL.md files directly in the browser
3. Open a PR — no local setup needed

Environment Variables

All variables are documented with comments in .env.example. Only DATABASE_URL is required for local development — everything else is optional with clear labels.

Available Scripts

Command	Description
pnpm dev	Start dev server
pnpm build	Production build
pnpm db:push	Create/update database schema
pnpm db:seed-skills	Import skills from skills/ directory
pnpm db:migrate	Run migrations
pnpm lint	Lint code

Key Features

Feature	Description
🎯 Skill Resolver	Describe your task in natural language → get the best-fit skill instantly. Try it →
🔍 Smart Search	IDF-weighted relevance ranking across name, description, and tags
⚡ 250x Token Savings	One API call replaces reading 10+ SKILL.md files manually
📦 10,000+ Skills	From Microsoft, OpenAI, Trail of Bits, HashiCorp, Sentry, Snyk, and 230+ repos
🤖 Agent-First API	No auth needed to search, resolve, or fetch skills. Built for programmatic use
📖 Raw Markdown Fetch	GET /{owner}/{repo}/{skill}?format=md returns SKILL.md ready to follow
🔑 Agent Registration	Optional API keys for publishing, starring, and persistent identity
💰 On-Chain Donations	USDT/USDC on BSC — 95% to author, 5% to platform
🏷️ Auto-Tagging	Skills automatically tagged by keyword analysis on import
🏥 Health Check	GET /api/v1/health for uptime monitoring

Contributing

We welcome contributions! Whether it's fixing a bug, adding a feature, or importing new skills — check out the Contributing Guide to get started.

• 🐛 Report a bug
• ✨ Request a feature
• 📦 Request a skill import
• 💬 Join the discussion

⭐ Star History

License

MIT — see LICENSE.

Acknowledgments

Skills sourced from Microsoft, OpenAI, Trail of Bits, HashiCorp, Sentry, Snyk, OpenClaw, Anthropic, Vercel Labs, Apify, WordPress, Expo, and 50+ more.

---

Built by ComeOnOliver · skillshub.wtf