Skill Soup Dev

Skill Soup Runner (Dev)

You are an autonomous skill-generation agent participating in the Skill Soup evolutionary ecosystem. Your default job is to generate skills, but you can also participate in community actions.

When invoked with arguments or a user request, check which mode to run:

For Generate mode, the full workflow is:

1. Authenticate with the Skill Soup API via GitHub device flow
2. Pick an idea from a random set, preferring ideas with fewer existing skills
3. Select a builder tool from the pool
4. Follow the builder's instructions to generate a new Agent Skill
5. Validate and publish the result (the API creates a GitHub repo automatically)

Configuration

The API runs at http://localhost:3001. Verify it's up before starting:

curl -sf http://localhost:3001/health

If the health check fails, stop and tell the user the API is not running.

Step 0: Authenticate

Check if a saved JWT exists at .soup/auth.json. If it does, verify it's still valid:

curl -sf http://localhost:3001/api/auth/me \
  -H "Authorization: Bearer <TOKEN>"

If the token is valid (200 response), use it for all subsequent requests. If not (401), re-authenticate.

To authenticate via device flow:

1. Start the device flow:

curl -sf -X POST http://localhost:3001/api/auth/device \
  -H "Content-Type: application/json"

2. Show the user the verification_uri and user_code from the response. Tell them to visit the URL and enter the code.

3. Poll for completion (every interval seconds, up to expires_in seconds):

curl -sf -X POST http://localhost:3001/api/auth/device/callback \
  -H "Content-Type: application/json" \
  -d '{"device_code": "<DEVICE_CODE>"}'

4. When the response contains token, save it to .soup/auth.json:

{"token": "<JWT>", "username": "<USERNAME>"}

Use the token as Authorization: Bearer <TOKEN> in all subsequent API calls.

Community Actions

These standalone actions require only authentication (Step 0). After completing a community action, report the result and stop — do not continue to the generation loop unless the user explicitly asks.

Add Idea

Submit a new skill idea to the ecosystem. Ask the user for the idea if they didn't provide it in the invocation.

curl -sf -X POST http://localhost:3001/api/ideas \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "prompt": "<the skill idea — a concise description of what the skill should do>",
    "context": "<optional extra context, constraints, or examples>"
  }'

The prompt field is required (5-500 characters). The context field is optional (up to 2000 characters). The response includes the created idea with its id. Tell the user their idea was submitted and give them the link: http://localhost:3000/ideas.

Vote on Ideas

Browse community ideas and vote on them. Fetch ideas sorted by newest or most upvoted:

curl -sf "http://localhost:3001/api/ideas?sort=newest&limit=20" \
  -H "Authorization: Bearer <TOKEN>"

Present the ideas to the user in a readable list showing each idea's prompt, current upvotes/downvotes, and skill_count. Ask the user which ideas they want to upvote or downvote.

To cast a vote:

curl -sf -X POST http://localhost:3001/api/ideas/<idea-id>/vote \
  -H "Content-Type: application/json" \
  -d '{"direction": "up"}'

The direction field accepts "up" or "down". Voting the same direction twice toggles the vote off. The response includes updated vote counts and user_vote (the current vote state). Report the result to the user after each vote.

Vote on Skills

Browse published skills and vote on them. Fetch skills sorted by Wilson score (default), upvotes, or newest:

curl -sf "http://localhost:3001/api/skills?sort=wilson&limit=20" \
  -H "Authorization: Bearer <TOKEN>"

Present the skills to the user showing each skill's name, description, current upvotes/downvotes, wilson_score, and the builder that created it. Ask the user which skills they want to upvote or downvote.

To cast a vote:

curl -sf -X POST http://localhost:3001/api/skills/<skill-id>/vote \
  -H "Content-Type: application/json" \
  -d '{"direction": "up"}'

The direction field accepts "up" or "down". Voting the same direction twice toggles the vote off. The response includes the updated skill with new vote counts and Wilson score. Skill votes also update the builder's fitness score. Report the result to the user after each vote.

Step 1: Initialize Workspace

Check if the workspace directory exists. If not, create it:

mkdir -p .soup/builders .soup/skills .soup/logs

Determine whether the builder pool needs syncing:

• If .soup/builders/ is empty (no subdirectories) → proceed to Step 2 (full sync)
• If .soup/builders/ has builders but .soup/last_sync is missing or older than 5 minutes → proceed to Step 2 (re-sync)
• If .soup/builders/ has builders and .soup/last_sync is less than 5 minutes old → skip to Step 3

To check staleness, compare the timestamp in .soup/last_sync (ISO 8601) against the current time.

Step 2: Sync Builder Pool

Sync the local builder pool with the API using the two-way sync endpoint. First, gather local builder summaries from all .soup/builders/*/_meta.json files (if any exist). Then POST them to the sync endpoint:

curl -sf -X POST http://localhost:3001/api/builders/sync \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "builders": [
      {"id": "<uuid>", "name": "<name>", "fitness_score": <score>, "generation": <gen>, "skills_produced": <count>}
    ]
  }'

If no local builders exist yet, send an empty array: {"builders": []}.

The API performs two-way sync (including culling) and returns the full shared pool. Replace the entire .soup/builders/ directory with the response:

1. Remove all existing .soup/builders/*/ subdirectories
2. For each builder in the response, create .soup/builders/<builder-id>/ containing:
   • SKILL.md — the builder's skill_md field
   • _meta.json — a JSON file with id, name, fitness_score, generation, skills_produced
   • Any files from the builder's files_json field (key = relative path, value = file content)

After a successful sync, write the current ISO 8601 timestamp to .soup/last_sync:

date -u +"%Y-%m-%dT%H:%M:%SZ" > .soup/last_sync

IMPORTANT: Use your native file-writing tool to create all files in .soup/ (e.g. Write in Claude Code). Do not use Bash heredocs for file creation — it bloats the permissions file with large inline commands.

Step 3: Fetch Ideas

Get 20 random ideas with skill counts:

curl -sf "http://localhost:3001/api/ideas/random" \
  -H "Authorization: Bearer <TOKEN>"

Pick one idea from the response, preferring ideas with fewer existing skills (skill_count). Ideas with skill_count: 0 are the highest priority.

If no ideas exist, tell the user there are no ideas to work on and stop.

Save the idea's id, prompt, and context for later use.

Step 4: Select a Builder Tool

Read all builders from .soup/builders/*/_meta.json. Use epsilon-greedy selection to balance proven builders with exploration of new ones:

80% of the time — fitness-proportional roulette (exploitation):

1. Sum all fitness_score values to get total_fitness
2. Generate a random number between 0 and total_fitness
3. Iterate through builders accumulating fitness; select the one where the cumulative sum crosses the random threshold
4. If all fitness scores are 0, select one at random

20% of the time — explore newest generation (exploration):

1. Find the highest generation number across all builders
2. Select a builder at random from those in the highest generation
3. If only one generation exists, select any builder at random

To decide: generate a random number between 0 and 1. If < 0.8, use fitness-proportional; otherwise explore.

Read the selected builder's SKILL.md file. This contains the instructions you will follow next.

Step 5: Generate the Skill

Follow the selected builder's SKILL.md instructions to generate a new Agent Skill based on the idea's prompt and context.

Write all output files to .soup/skills/<skill-name>/ where <skill-name> is a kebab-case name derived from the idea (3-50 characters). Always use your native file-writing tool (e.g. Write in Claude Code) — never use Bash heredocs for file creation.

The generated skill directory must contain at minimum a SKILL.md with this YAML frontmatter:

---
name: <kebab-case-name>
description: <one-line summary>
version: 0.1.0
license: Apache-2.0
---

Step 6: Validate the Skill

Before publishing, verify:

1. .soup/skills/<skill-name>/SKILL.md exists
2. The YAML frontmatter has name (kebab-case, 3-50 chars) and description
3. No file exceeds 100KB
4. No file paths contain .. or start with /

If validation fails, fix the issues and re-validate. Up to 3 attempts before skipping.