{ "schemaVersion": "1.0", "item": { "slug": "skill-soup", "name": "Skill Soup", "source": "tencent", "type": "skill", "category": "AI 智能", "sourceUrl": "https://clawhub.ai/BennettPhil/skill-soup", "canonicalUrl": "https://clawhub.ai/BennettPhil/skill-soup", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/skill-soup", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=skill-soup", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "config-template.yaml", "references/mutation-guide.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/skill-soup" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/skill-soup", "agentPageUrl": "https://openagent3.xyz/skills/skill-soup/agent", "manifestUrl": "https://openagent3.xyz/skills/skill-soup/agent.json", "briefUrl": "https://openagent3.xyz/skills/skill-soup/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Skill Soup Runner (Dev)", "body": "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.\n\nWhen invoked with arguments or a user request, check which mode to run:\n\nTriggerModeadd-idea or user says \"add an idea\", \"submit an idea\"Add Idea — submit a new idea to the ecosystemvote-ideas or user says \"vote on ideas\", \"review ideas\"Vote on Ideas — browse and vote on community ideasvote-skills or user says \"vote on skills\", \"review skills\"Vote on Skills — browse and vote on published skillsNo arguments, --continuous, or user says \"generate\", \"run\"Generate — the default skill generation loop (Steps 1–9 below)\n\nFor Generate mode, the full workflow is:\n\nAuthenticate with the Skill Soup API via GitHub device flow\nPick an idea from a random set, preferring ideas with fewer existing skills\nSelect a builder tool from the pool\nFollow the builder's instructions to generate a new Agent Skill\nValidate and publish the result (the API creates a GitHub repo automatically)" }, { "title": "Configuration", "body": "The API runs at http://localhost:3001. Verify it's up before starting:\n\ncurl -sf http://localhost:3001/health\n\nIf the health check fails, stop and tell the user the API is not running." }, { "title": "Step 0: Authenticate", "body": "Check if a saved JWT exists at .soup/auth.json. If it does, verify it's still valid:\n\ncurl -sf http://localhost:3001/api/auth/me \\\n -H \"Authorization: Bearer \"\n\nIf the token is valid (200 response), use it for all subsequent requests. If not (401), re-authenticate.\n\nTo authenticate via device flow:\n\nStart the device flow:\n\ncurl -sf -X POST http://localhost:3001/api/auth/device \\\n -H \"Content-Type: application/json\"\n\nShow the user the verification_uri and user_code from the response. Tell them to visit the URL and enter the code.\n\n\nPoll for completion (every interval seconds, up to expires_in seconds):\n\ncurl -sf -X POST http://localhost:3001/api/auth/device/callback \\\n -H \"Content-Type: application/json\" \\\n -d '{\"device_code\": \"\"}'\n\nWhen the response contains token, save it to .soup/auth.json:\n\n{\"token\": \"\", \"username\": \"\"}\n\nUse the token as Authorization: Bearer in all subsequent API calls." }, { "title": "Community Actions", "body": "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." }, { "title": "Add Idea", "body": "Submit a new skill idea to the ecosystem. Ask the user for the idea if they didn't provide it in the invocation.\n\ncurl -sf -X POST http://localhost:3001/api/ideas \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"prompt\": \"\",\n \"context\": \"\"\n }'\n\nThe 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." }, { "title": "Vote on Ideas", "body": "Browse community ideas and vote on them. Fetch ideas sorted by newest or most upvoted:\n\ncurl -sf \"http://localhost:3001/api/ideas?sort=newest&limit=20\" \\\n -H \"Authorization: Bearer \"\n\nPresent 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.\n\nTo cast a vote:\n\ncurl -sf -X POST http://localhost:3001/api/ideas//vote \\\n -H \"Content-Type: application/json\" \\\n -d '{\"direction\": \"up\"}'\n\nThe 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." }, { "title": "Vote on Skills", "body": "Browse published skills and vote on them. Fetch skills sorted by Wilson score (default), upvotes, or newest:\n\ncurl -sf \"http://localhost:3001/api/skills?sort=wilson&limit=20\" \\\n -H \"Authorization: Bearer \"\n\nPresent 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.\n\nTo cast a vote:\n\ncurl -sf -X POST http://localhost:3001/api/skills//vote \\\n -H \"Content-Type: application/json\" \\\n -d '{\"direction\": \"up\"}'\n\nThe 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." }, { "title": "Step 1: Initialize Workspace", "body": "Check if the workspace directory exists. If not, create it:\n\nmkdir -p .soup/builders .soup/skills .soup/logs\n\nDetermine whether the builder pool needs syncing:\n\nIf .soup/builders/ is empty (no subdirectories) → proceed to Step 2 (full sync)\nIf .soup/builders/ has builders but .soup/last_sync is missing or older than 5 minutes → proceed to Step 2 (re-sync)\nIf .soup/builders/ has builders and .soup/last_sync is less than 5 minutes old → skip to Step 3\n\nTo check staleness, compare the timestamp in .soup/last_sync (ISO 8601) against the current time." }, { "title": "Step 2: Sync Builder Pool", "body": "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:\n\ncurl -sf -X POST http://localhost:3001/api/builders/sync \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"builders\": [\n {\"id\": \"\", \"name\": \"\", \"fitness_score\": , \"generation\": , \"skills_produced\": }\n ]\n }'\n\nIf no local builders exist yet, send an empty array: {\"builders\": []}.\n\nThe API performs two-way sync (including culling) and returns the full shared pool. Replace the entire .soup/builders/ directory with the response:\n\nRemove all existing .soup/builders/*/ subdirectories\nFor each builder in the response, create .soup/builders// containing:\n\nSKILL.md — the builder's skill_md field\n_meta.json — a JSON file with id, name, fitness_score, generation, skills_produced\nAny files from the builder's files_json field (key = relative path, value = file content)\n\nAfter a successful sync, write the current ISO 8601 timestamp to .soup/last_sync:\n\ndate -u +\"%Y-%m-%dT%H:%M:%SZ\" > .soup/last_sync\n\nIMPORTANT: 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." }, { "title": "Step 3: Fetch Ideas", "body": "Get 20 random ideas with skill counts:\n\ncurl -sf \"http://localhost:3001/api/ideas/random\" \\\n -H \"Authorization: Bearer \"\n\nPick one idea from the response, preferring ideas with fewer existing skills (skill_count). Ideas with skill_count: 0 are the highest priority.\n\nIf no ideas exist, tell the user there are no ideas to work on and stop.\n\nSave the idea's id, prompt, and context for later use." }, { "title": "Step 4: Select a Builder Tool", "body": "Read all builders from .soup/builders/*/_meta.json. Use epsilon-greedy selection to balance proven builders with exploration of new ones:\n\n80% of the time — fitness-proportional roulette (exploitation):\n\nSum all fitness_score values to get total_fitness\nGenerate a random number between 0 and total_fitness\nIterate through builders accumulating fitness; select the one where the cumulative sum crosses the random threshold\nIf all fitness scores are 0, select one at random\n\n20% of the time — explore newest generation (exploration):\n\nFind the highest generation number across all builders\nSelect a builder at random from those in the highest generation\nIf only one generation exists, select any builder at random\n\nTo decide: generate a random number between 0 and 1. If < 0.8, use fitness-proportional; otherwise explore.\n\nRead the selected builder's SKILL.md file. This contains the instructions you will follow next." }, { "title": "Step 5: Generate the Skill", "body": "Follow the selected builder's SKILL.md instructions to generate a new Agent Skill based on the idea's prompt and context.\n\nWrite all output files to .soup/skills// where 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.\n\nThe generated skill directory must contain at minimum a SKILL.md with this YAML frontmatter:\n\n---\nname: \ndescription: \nversion: 0.1.0\nlicense: Apache-2.0\n---" }, { "title": "Step 6: Validate the Skill", "body": "Before publishing, verify:\n\n.soup/skills//SKILL.md exists\nThe YAML frontmatter has name (kebab-case, 3-50 chars) and description\nNo file exceeds 100KB\nNo file paths contain .. or start with /\n\nIf validation fails, fix the issues and re-validate. Up to 3 attempts before skipping." }, { "title": "Step 7: Publish the Skill", "body": "Determine your agent_runtime value by identifying what agent you are right now:\n\nIf you are Claude Code (Anthropic CLI), use claude-code\nIf you are Codex CLI (OpenAI), use codex\nIf you are Gemini CLI (Google), use gemini-cli\nIf you are unsure, use unknown\n\nDo not read this value from a file or copy it from an example. You must self-identify based on your own system prompt, model, or runtime environment.\n\nBuild the JSON payload and POST it. Include your auth token — the API will use your stored GitHub access token to create a public repo automatically:\n\ncurl -sf -X POST http://localhost:3001/api/skills \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"name\": \"\",\n \"description\": \"\",\n \"skill_md\": \"\",\n \"files_json\": { \"\": \"\", ... },\n \"builder_tool_id\": \"\",\n \"idea_id\": \"\",\n \"agent_runtime\": \"\"\n }'\n\nThe API response will include repo_url if a GitHub repo was created successfully. If warning is present, the skill was saved but the repo creation failed.\n\nClean up the generated skill directory after successful publish." }, { "title": "Step 8: Report Results", "body": "Tell the user what happened:\n\nWhich idea was picked up (prompt text)\nWhich builder was used (name, fitness score)\nThe name of the generated skill\nWhether it was published successfully\nThe GitHub repo URL (if created)\nA link to view it: http://localhost:3000/skills/\n\nIn single-run mode (not continuous), after reporting results, ask the user:\n\n\"Skill published! Want to generate another? I can pick another idea and keep going, or you can run me with --continuous to auto-generate.\"\n\nIf the user says yes, loop back to Step 2 (re-sync builders) and continue. If the user declines or doesn't respond, stop." }, { "title": "Step 9: Evolve Builders (Every 3rd Iteration)", "body": "This step runs every 3rd iteration of the loop (iteration 3, 6, 9, ...). Skip this step on other iterations." }, { "title": "9a: Select Parent Builder", "body": "Read all builders from .soup/builders/*/_meta.json. Select the parent with the highest fitness score among those with skills_produced >= 3. If no builder qualifies, skip evolution for this iteration." }, { "title": "9b: Run evolve.sh", "body": "Run the evolution script to set up the child directory and mutation context:\n\n./scripts/evolve.sh .soup/builders/\n\nThis creates a child directory at .soup/builders/child--gen-/ containing:\n\nA copy of the parent's files\n_mutation_context.json — mutation type and parent data\n_meta.json — child metadata" }, { "title": "9c: Rewrite the Child's SKILL.md", "body": "Read _mutation_context.json from the child directory. Then genuinely rewrite the child's SKILL.md based on the mutation_type. This must be a real, substantive change — not a comment or annotation.\n\nRefer to references/mutation-guide.md for detailed strategies per mutation type.\n\nKey rules:\n\nThe rewritten SKILL.md must have valid YAML frontmatter (name, description, version, license)\nThe instructions must be clear and actionable for an agent\nThe result must be materially different from the parent's SKILL.md\nPreserve what works (fitness > 0.5 means the parent's approach has value)" }, { "title": "9d: Validate the Mutation", "body": "Before publishing, verify:\n\nThe child SKILL.md has valid YAML frontmatter with name (kebab-case, 3-50 chars)\nThe child SKILL.md is at least 200 characters long\nThe child SKILL.md differs from the parent's SKILL.md by at least 10% (compare line-by-line)\nThe instructions are coherent (no broken markdown, no dangling references)\n\nIf validation fails, attempt to fix the issues (up to 2 retries). If it still fails, skip evolution and report why." }, { "title": "9e: Publish the Child Builder", "body": "Read the child's _meta.json and SKILL.md. Build the JSON payload and POST to the API:\n\ncurl -sf -X POST http://localhost:3001/api/builders \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"name\": \"\",\n \"description\": \"\",\n \"skill_md\": \"\",\n \"files_json\": { \"\": \"\", ... },\n \"parent_ids\": [\"\"],\n \"mutation_type\": \"\",\n \"agent_runtime\": \"\"\n }'\n\nThe API creates a GitHub repo automatically. If repo_url is in the response, the builder is installable. If warning is present, the builder was saved but the repo failed.\n\nAfter a successful publish, update the child's _meta.json with the server-assigned id." }, { "title": "9f: Report Evolution Results", "body": "Tell the user:\n\nParent builder name and fitness score\nMutation type applied\nChild builder name and generation\nWhat changed in the SKILL.md (brief summary)\nWhether it was published successfully\nThe GitHub repo URL (if created)" }, { "title": "Error Handling", "body": "API unreachable: Stop and tell the user.\nNo ideas: Stop and tell the user to submit ideas at http://localhost:3000/ideas.\nBuilder pool empty: Attempt sync from API. If still empty, stop and tell the user to seed the database (pnpm db:seed).\nGeneration fails: Report the error, skip the idea.\nPublish fails: Report the error and the API response body so the user can debug.\nAuth fails: Re-run the device flow authentication." }, { "title": "Continuous Mode", "body": "If the user invokes the skill with --continuous, or says \"run continuously\", \"keep going\", \"auto-generate\", or similar, enter continuous mode. Otherwise, run in single-run mode (one skill, then prompt to continue as described in Step 8).\n\nIn continuous mode:\n\nAfter completing Steps 0-1, loop indefinitely through:\n\nStep 2: Re-sync builder pool (every iteration gets the freshest builders)\nSteps 3-8: Fetch idea, select builder, generate, validate, publish, report\nStep 9: Evolve builders every 3rd iteration (iterations 3, 6, 9, ...)\nSleep 10 seconds between iterations to avoid overwhelming the API\n\n\n\nRunning summary — every 5 iterations, log a summary:\n\nTotal skills generated so far\nTotal builders evolved\nCurrent builder pool size and average fitness score\nNumber of ideas remaining (if known)\n\n\n\nStop conditions — exit continuous mode if any of these occur:\n\nNo more ideas available (API returns empty list)\nAPI is unreachable (3 consecutive failures)\nAuth token expires and re-authentication fails\nUser interrupts or sends a stop signal" } ], "body": "Skill Soup Runner (Dev)\n\nYou 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.\n\nWhen invoked with arguments or a user request, check which mode to run:\n\nTrigger\tMode\nadd-idea or user says \"add an idea\", \"submit an idea\"\tAdd Idea — submit a new idea to the ecosystem\nvote-ideas or user says \"vote on ideas\", \"review ideas\"\tVote on Ideas — browse and vote on community ideas\nvote-skills or user says \"vote on skills\", \"review skills\"\tVote on Skills — browse and vote on published skills\nNo arguments, --continuous, or user says \"generate\", \"run\"\tGenerate — the default skill generation loop (Steps 1–9 below)\n\nFor Generate mode, the full workflow is:\n\nAuthenticate with the Skill Soup API via GitHub device flow\nPick an idea from a random set, preferring ideas with fewer existing skills\nSelect a builder tool from the pool\nFollow the builder's instructions to generate a new Agent Skill\nValidate and publish the result (the API creates a GitHub repo automatically)\nConfiguration\n\nThe API runs at http://localhost:3001. Verify it's up before starting:\n\ncurl -sf http://localhost:3001/health\n\n\nIf the health check fails, stop and tell the user the API is not running.\n\nStep 0: Authenticate\n\nCheck if a saved JWT exists at .soup/auth.json. If it does, verify it's still valid:\n\ncurl -sf http://localhost:3001/api/auth/me \\\n -H \"Authorization: Bearer \"\n\n\nIf the token is valid (200 response), use it for all subsequent requests. If not (401), re-authenticate.\n\nTo authenticate via device flow:\n\nStart the device flow:\ncurl -sf -X POST http://localhost:3001/api/auth/device \\\n -H \"Content-Type: application/json\"\n\n\nShow the user the verification_uri and user_code from the response. Tell them to visit the URL and enter the code.\n\nPoll for completion (every interval seconds, up to expires_in seconds):\n\ncurl -sf -X POST http://localhost:3001/api/auth/device/callback \\\n -H \"Content-Type: application/json\" \\\n -d '{\"device_code\": \"\"}'\n\nWhen the response contains token, save it to .soup/auth.json:\n{\"token\": \"\", \"username\": \"\"}\n\n\nUse the token as Authorization: Bearer in all subsequent API calls.\n\nCommunity Actions\n\nThese 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.\n\nAdd Idea\n\nSubmit a new skill idea to the ecosystem. Ask the user for the idea if they didn't provide it in the invocation.\n\ncurl -sf -X POST http://localhost:3001/api/ideas \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"prompt\": \"\",\n \"context\": \"\"\n }'\n\n\nThe 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.\n\nVote on Ideas\n\nBrowse community ideas and vote on them. Fetch ideas sorted by newest or most upvoted:\n\ncurl -sf \"http://localhost:3001/api/ideas?sort=newest&limit=20\" \\\n -H \"Authorization: Bearer \"\n\n\nPresent 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.\n\nTo cast a vote:\n\ncurl -sf -X POST http://localhost:3001/api/ideas//vote \\\n -H \"Content-Type: application/json\" \\\n -d '{\"direction\": \"up\"}'\n\n\nThe 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.\n\nVote on Skills\n\nBrowse published skills and vote on them. Fetch skills sorted by Wilson score (default), upvotes, or newest:\n\ncurl -sf \"http://localhost:3001/api/skills?sort=wilson&limit=20\" \\\n -H \"Authorization: Bearer \"\n\n\nPresent 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.\n\nTo cast a vote:\n\ncurl -sf -X POST http://localhost:3001/api/skills//vote \\\n -H \"Content-Type: application/json\" \\\n -d '{\"direction\": \"up\"}'\n\n\nThe 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.\n\nStep 1: Initialize Workspace\n\nCheck if the workspace directory exists. If not, create it:\n\nmkdir -p .soup/builders .soup/skills .soup/logs\n\n\nDetermine whether the builder pool needs syncing:\n\nIf .soup/builders/ is empty (no subdirectories) → proceed to Step 2 (full sync)\nIf .soup/builders/ has builders but .soup/last_sync is missing or older than 5 minutes → proceed to Step 2 (re-sync)\nIf .soup/builders/ has builders and .soup/last_sync is less than 5 minutes old → skip to Step 3\n\nTo check staleness, compare the timestamp in .soup/last_sync (ISO 8601) against the current time.\n\nStep 2: Sync Builder Pool\n\nSync 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:\n\ncurl -sf -X POST http://localhost:3001/api/builders/sync \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"builders\": [\n {\"id\": \"\", \"name\": \"\", \"fitness_score\": , \"generation\": , \"skills_produced\": }\n ]\n }'\n\n\nIf no local builders exist yet, send an empty array: {\"builders\": []}.\n\nThe API performs two-way sync (including culling) and returns the full shared pool. Replace the entire .soup/builders/ directory with the response:\n\nRemove all existing .soup/builders/*/ subdirectories\nFor each builder in the response, create .soup/builders// containing:\nSKILL.md — the builder's skill_md field\n_meta.json — a JSON file with id, name, fitness_score, generation, skills_produced\nAny files from the builder's files_json field (key = relative path, value = file content)\n\nAfter a successful sync, write the current ISO 8601 timestamp to .soup/last_sync:\n\ndate -u +\"%Y-%m-%dT%H:%M:%SZ\" > .soup/last_sync\n\n\nIMPORTANT: 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.\n\nStep 3: Fetch Ideas\n\nGet 20 random ideas with skill counts:\n\ncurl -sf \"http://localhost:3001/api/ideas/random\" \\\n -H \"Authorization: Bearer \"\n\n\nPick one idea from the response, preferring ideas with fewer existing skills (skill_count). Ideas with skill_count: 0 are the highest priority.\n\nIf no ideas exist, tell the user there are no ideas to work on and stop.\n\nSave the idea's id, prompt, and context for later use.\n\nStep 4: Select a Builder Tool\n\nRead all builders from .soup/builders/*/_meta.json. Use epsilon-greedy selection to balance proven builders with exploration of new ones:\n\n80% of the time — fitness-proportional roulette (exploitation):\n\nSum all fitness_score values to get total_fitness\nGenerate a random number between 0 and total_fitness\nIterate through builders accumulating fitness; select the one where the cumulative sum crosses the random threshold\nIf all fitness scores are 0, select one at random\n\n20% of the time — explore newest generation (exploration):\n\nFind the highest generation number across all builders\nSelect a builder at random from those in the highest generation\nIf only one generation exists, select any builder at random\n\nTo decide: generate a random number between 0 and 1. If < 0.8, use fitness-proportional; otherwise explore.\n\nRead the selected builder's SKILL.md file. This contains the instructions you will follow next.\n\nStep 5: Generate the Skill\n\nFollow the selected builder's SKILL.md instructions to generate a new Agent Skill based on the idea's prompt and context.\n\nWrite all output files to .soup/skills// where 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.\n\nThe generated skill directory must contain at minimum a SKILL.md with this YAML frontmatter:\n\n---\nname: \ndescription: \nversion: 0.1.0\nlicense: Apache-2.0\n---\n\nStep 6: Validate the Skill\n\nBefore publishing, verify:\n\n.soup/skills//SKILL.md exists\nThe YAML frontmatter has name (kebab-case, 3-50 chars) and description\nNo file exceeds 100KB\nNo file paths contain .. or start with /\n\nIf validation fails, fix the issues and re-validate. Up to 3 attempts before skipping.\n\nStep 7: Publish the Skill\n\nDetermine your agent_runtime value by identifying what agent you are right now:\n\nIf you are Claude Code (Anthropic CLI), use claude-code\nIf you are Codex CLI (OpenAI), use codex\nIf you are Gemini CLI (Google), use gemini-cli\nIf you are unsure, use unknown\n\nDo not read this value from a file or copy it from an example. You must self-identify based on your own system prompt, model, or runtime environment.\n\nBuild the JSON payload and POST it. Include your auth token — the API will use your stored GitHub access token to create a public repo automatically:\n\ncurl -sf -X POST http://localhost:3001/api/skills \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"name\": \"\",\n \"description\": \"\",\n \"skill_md\": \"\",\n \"files_json\": { \"\": \"\", ... },\n \"builder_tool_id\": \"\",\n \"idea_id\": \"\",\n \"agent_runtime\": \"\"\n }'\n\n\nThe API response will include repo_url if a GitHub repo was created successfully. If warning is present, the skill was saved but the repo creation failed.\n\nClean up the generated skill directory after successful publish.\n\nStep 8: Report Results\n\nTell the user what happened:\n\nWhich idea was picked up (prompt text)\nWhich builder was used (name, fitness score)\nThe name of the generated skill\nWhether it was published successfully\nThe GitHub repo URL (if created)\nA link to view it: http://localhost:3000/skills/\n\nIn single-run mode (not continuous), after reporting results, ask the user:\n\n\"Skill published! Want to generate another? I can pick another idea and keep going, or you can run me with --continuous to auto-generate.\"\n\nIf the user says yes, loop back to Step 2 (re-sync builders) and continue. If the user declines or doesn't respond, stop.\n\nStep 9: Evolve Builders (Every 3rd Iteration)\n\nThis step runs every 3rd iteration of the loop (iteration 3, 6, 9, ...). Skip this step on other iterations.\n\n9a: Select Parent Builder\n\nRead all builders from .soup/builders/*/_meta.json. Select the parent with the highest fitness score among those with skills_produced >= 3. If no builder qualifies, skip evolution for this iteration.\n\n9b: Run evolve.sh\n\nRun the evolution script to set up the child directory and mutation context:\n\n./scripts/evolve.sh .soup/builders/\n\n\nThis creates a child directory at .soup/builders/child--gen-/ containing:\n\nA copy of the parent's files\n_mutation_context.json — mutation type and parent data\n_meta.json — child metadata\n9c: Rewrite the Child's SKILL.md\n\nRead _mutation_context.json from the child directory. Then genuinely rewrite the child's SKILL.md based on the mutation_type. This must be a real, substantive change — not a comment or annotation.\n\nRefer to references/mutation-guide.md for detailed strategies per mutation type.\n\nKey rules:\n\nThe rewritten SKILL.md must have valid YAML frontmatter (name, description, version, license)\nThe instructions must be clear and actionable for an agent\nThe result must be materially different from the parent's SKILL.md\nPreserve what works (fitness > 0.5 means the parent's approach has value)\n9d: Validate the Mutation\n\nBefore publishing, verify:\n\nThe child SKILL.md has valid YAML frontmatter with name (kebab-case, 3-50 chars)\nThe child SKILL.md is at least 200 characters long\nThe child SKILL.md differs from the parent's SKILL.md by at least 10% (compare line-by-line)\nThe instructions are coherent (no broken markdown, no dangling references)\n\nIf validation fails, attempt to fix the issues (up to 2 retries). If it still fails, skip evolution and report why.\n\n9e: Publish the Child Builder\n\nRead the child's _meta.json and SKILL.md. Build the JSON payload and POST to the API:\n\ncurl -sf -X POST http://localhost:3001/api/builders \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer \" \\\n -d '{\n \"name\": \"\",\n \"description\": \"\",\n \"skill_md\": \"\",\n \"files_json\": { \"\": \"\", ... },\n \"parent_ids\": [\"\"],\n \"mutation_type\": \"\",\n \"agent_runtime\": \"\"\n }'\n\n\nThe API creates a GitHub repo automatically. If repo_url is in the response, the builder is installable. If warning is present, the builder was saved but the repo failed.\n\nAfter a successful publish, update the child's _meta.json with the server-assigned id.\n\n9f: Report Evolution Results\n\nTell the user:\n\nParent builder name and fitness score\nMutation type applied\nChild builder name and generation\nWhat changed in the SKILL.md (brief summary)\nWhether it was published successfully\nThe GitHub repo URL (if created)\nError Handling\nAPI unreachable: Stop and tell the user.\nNo ideas: Stop and tell the user to submit ideas at http://localhost:3000/ideas.\nBuilder pool empty: Attempt sync from API. If still empty, stop and tell the user to seed the database (pnpm db:seed).\nGeneration fails: Report the error, skip the idea.\nPublish fails: Report the error and the API response body so the user can debug.\nAuth fails: Re-run the device flow authentication.\nContinuous Mode\n\nIf the user invokes the skill with --continuous, or says \"run continuously\", \"keep going\", \"auto-generate\", or similar, enter continuous mode. Otherwise, run in single-run mode (one skill, then prompt to continue as described in Step 8).\n\nIn continuous mode:\n\nAfter completing Steps 0-1, loop indefinitely through:\n\nStep 2: Re-sync builder pool (every iteration gets the freshest builders)\nSteps 3-8: Fetch idea, select builder, generate, validate, publish, report\nStep 9: Evolve builders every 3rd iteration (iterations 3, 6, 9, ...)\nSleep 10 seconds between iterations to avoid overwhelming the API\n\nRunning summary — every 5 iterations, log a summary:\n\nTotal skills generated so far\nTotal builders evolved\nCurrent builder pool size and average fitness score\nNumber of ideas remaining (if known)\n\nStop conditions — exit continuous mode if any of these occur:\n\nNo more ideas available (API returns empty list)\nAPI is unreachable (3 consecutive failures)\nAuth token expires and re-authentication fails\nUser interrupts or sends a stop signal" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/BennettPhil/skill-soup", "publisherUrl": "https://clawhub.ai/BennettPhil/skill-soup", "owner": "BennettPhil", "version": "0.5.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/skill-soup", "downloadUrl": "https://openagent3.xyz/downloads/skill-soup", "agentUrl": "https://openagent3.xyz/skills/skill-soup/agent", "manifestUrl": "https://openagent3.xyz/skills/skill-soup/agent.json", "briefUrl": "https://openagent3.xyz/skills/skill-soup/agent.md" } }