---
name: spec-hub
description: Search the SPEC HUB catalogue for an agent workflow that matches a natural-language brief, then fetch the combined markdown specification. Use whenever the user mentions following a project convention, a specification, a workflow, or asks "is there a spec for…".
---

# SPEC HUB

SPEC HUB is a remote library of agent specifications composed into workflows. This skill lets you discover the right workflow for the task at hand and pull its combined markdown so you can follow it precisely.

## When to use

Trigger this skill when the user:
- Asks for "the spec", "our convention", or "the workflow" for something.
- Starts a new feature or project where established specifications likely apply.
- Mentions a stack or pattern (e.g. "FastAPI service", "React component", "REST endpoint").

## How it works

1. **Search.** Send a concise natural-language description of the task to:

   `POST https://spec.playwithai.fun/api/public/search-workflow`

   Body:
   ```json
   { "query": "<one or two sentences describing what the user wants to build>" }
   ```

   Header:
   ```
   x-spec-hub-api-key: <uuid>
   ```

   Response:
   ```json
   {
     "matches": [
       {
         "id": "<uuid>",
         "name": "<workflow name>",
         "description": "<short description>",
         "reason": "<why this matches>",
         "score": 0.0,
         "download_url": "https://spec.playwithai.fun/api/public/workflow/<id>"
       }
     ]
   }
   ```

2. **Pick.** Choose the highest-scoring match whose `reason` aligns with the user's intent. If no result scores above 0.4, tell the user no workflow applies and proceed without one.

3. **Fetch.** `GET` the `download_url` to retrieve the combined markdown bundle of every spec in the workflow, in order. Treat it as authoritative project context for the task.

4. **Apply.** Follow the rules in the markdown verbatim while implementing. Cite the workflow name when you reference a rule so the user can audit it.

## Example

```bash
curl -s -X POST "https://spec.playwithai.fun/api/public/search-workflow" \
  -H "Content-Type: application/json" \
  -H "x-spec-hub-api-key: $SPEC_HUB_API_KEY" \
  -d '{"query":"new TypeScript React app with strict typing and a uniform API contract"}'
```

Then:

```bash
curl -s "https://spec.playwithai.fun/api/public/workflow/<id>"
```

## Notes

- Configure `SPEC_HUB_API_KEY` in your agent environment and send it as `x-spec-hub-api-key`.
- The search endpoint requires a valid, unexpired API key.
- All content is markdown; no parsing tricks needed.
- If SPEC HUB is unreachable, fall back to your normal behaviour and tell the user.