spawn-instance
Clone this Aeon agent into a new GitHub repo - fork, configure skills, validate, and register in the fleet
- License 许可
- MIT
- 所属仓库
- aeonfun/aeon
- 最近更新
- 2026-11-15
- Stars
- ★ 793
- Forks
- 308
01 前言 Front Matter
- name
- spawn-instance
- metadata
- { "var": "", "tags": [ "dev" ], "title": "Spawn Instance", "category": "core" }
- description
- Clone this Aeon agent into a new GitHub repo - fork, configure skills, validate, and register in the fleet
03 SKILL.md 正文
<!-- autoresearch: variation C — robust: skill-existence validation, exit taxonomy, idempotent recovery, dynamic SETUP.md, pre/post-flight verification -->
${var} — Name and purpose of the new instance. Format
name: purpose, e.g.crypto-tracker: monitor DeFi protocols and token movements. If empty, notify the owner and stop with exitSPAWN_INVALID_VAR.
Today is ${today}. Create a new Aeon instance by forking this repo, configuring it for a specific purpose, validating the configuration, and registering it in the fleet.
Read memory/MEMORY.md at the start for context.
Security Model
This skill creates the repo and configuration but does NOT propagate secrets.
The new instance is inert until the owner manually sets secrets (ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN, plus notification secrets).
Each instance has its own API keys for billing isolation and blast-radius containment.
Exit Taxonomy
Every run ends with one of these status codes, written to the log and (where relevant) included in the notification:
| Code | Meaning |
|---|---|
SPAWN_OK |
Fork created, configured, pushed, Actions enabled, registered. |
SPAWN_FORK_EXISTS_RECOVERED |
Fork already existed but wasn't registered → configured + registered now. |
SPAWN_FORK_EXISTS_REGISTERED |
Fork exists AND is already registered and not archived — refused, no change. |
SPAWN_INVALID_VAR |
var was empty or couldn't be parsed into name: purpose. |
SPAWN_NO_SKILLS |
After validation, the skill plan was empty — refused. |
SPAWN_FORK_FAILED |
gh repo fork and the fallback forks API both failed. |
SPAWN_PUSH_FAILED |
Fork created but push failed — fork left in place, recovery instructions emitted. |
SPAWN_ACTIONS_FAILED |
Configuration pushed but enabling Actions failed — recovery instructions emitted. |
SPAWN_API_ERROR |
Any other GitHub API failure not covered above. |
Steps
1. Parse and validate the var
- If
${var}is empty, logSPAWN_INVALID_VAR: empty vartomemory/logs/${today}.md, notify:spawn-instance: empty var — re-run with "name: purpose", and stop. - Split on the first
:— left isNAME_RAW, right isPURPOSE(trim whitespace). If either is empty, exitSPAWN_INVALID_VAR. - Derive
NAME: lowercaseNAME_RAW, replace non-alphanumeric runs with-, strip leading/trailing-, truncate to 40 chars. If empty after sanitization, exitSPAWN_INVALID_VAR. - Set
REPO_NAME="aeon-${NAME}".
2. Pre-flight checks
Shell shape. Each Bash call is one allowed command (pipes are fine). The run refuses a call that sets a variable (OWNER=$(gh api ...), TMPDIR=$(mktemp -d)), uses if / for / while or a [ ... ] test, joins commands with ;, && or || (including || { echo ...; exit 1; }), or starts with cd DIR, and find, rm, awk, basename, mktemp, seq and sleep are not allowed commands; each refusal costs a model turn. So run each gh / git command as its own call, read what it prints and write that value into later commands literally (the <OWNER>, <REPO_NAME> style placeholders in the snippets); turn each || exit into the prose check after the call; run git in the clone with git -C <dir>; write files with Write/Edit; and do the memory reset deletes inside one python3 -c call.
Run each as its own call:
gh auth status
If it fails, log SPAWN_API_ERROR: gh not authenticated and stop.
gh api user --jq '.login'
It prints OWNER. If it fails, log SPAWN_API_ERROR: cannot read user and stop.
gh repo view --json nameWithOwner -q .nameWithOwner
It prints PARENT_REPO. If the current repo is itself a fork, use the upstream as the parent; this prints PARENT_UPSTREAM:
gh api repos/<PARENT_REPO> --jq '.parent.full_name // .full_name'
Check rate limit:
gh api rate_limit --jq '.resources.core.remaining'
It prints REMAINING. If it is below 50 (or empty, which counts as 0), log SPAWN_API_ERROR: rate limit too low (<REMAINING>) and stop.
3. Check the fleet registry
Read memory/instances.json. If it doesn't exist, create it with {"instances": []}.
{
"instances": [
{
"name": "crypto-tracker",
"repo": "OWNER/aeon-crypto-tracker",
"purpose": "monitor DeFi protocols and token movements",
"created": "2026-04-20",
"status": "pending_secrets",
"skills_enabled": ["token-movers", "defi-overview", "heartbeat"],
"parent": "OWNER/aeon"
}
]
}
- If an entry with
name == NAMEexists andstatus != "archived", exitSPAWN_FORK_EXISTS_REGISTERED, notify, and stop. - If an entry exists and is archived, remove it — the new run replaces it.
4. Build the skill plan from the live catalog
Do not use a hardcoded skill list. The catalog in earlier revisions contained broken names (wallet-digest, trending-coins, tweet-digest, hn-digest — none of which exist in skills/). Always enumerate live.
Build the live catalog of available skills and their tags/description in one call (a shell for loop is refused; the loop lives inside node -e). It prints each skill's name and the frontmatter between its first two --- lines, skipping directories with no SKILL.md:
node -e 'const fs=require("fs"); for (const d of fs.readdirSync("skills").sort()) { const f="skills/"+d+"/SKILL.md"; if (!fs.existsSync(f)) continue; const m=fs.readFileSync(f,"utf8").split(/^---[^\n]*$/m)[1] || ""; console.log("== "+d+"\n"+m.trim()) }'
For each skill, parse the frontmatter description: and tags: lines. Classify the purpose into themes by keyword match (case-insensitive) and pick skills whose description or tags overlap:
| Purpose keywords | Prefer skills matching tags / keywords |
|---|---|
crypto, defi, token, chain, wallet |
tags [crypto] or description contains token/defi/chain |
research, paper, academic, science |
tags [research] or name contains paper/research/deep-research |
social, twitter, x , tweet, farcaster |
tags [social] or name contains tweet/twitter/farcaster/reply |
news, digest, feed, brief |
name contains digest/brief/morning/rss/hacker-news |
dev, code, github, repo, pr |
tags [dev] or name contains github/code/repo/pr-/changelog |
security, vuln, audit |
tags [security] or name contains security/vuln/audit |
prediction, polymarket, kalshi, market |
name contains polymarket/kalshi/market/narrative |
Rules:
- Cap at 8 content skills. Rank by keyword density in description against purpose; tie-break by name.
- Always include
heartbeatif the fileskills/heartbeat/SKILL.mdexists (health monitoring). - If the purpose doesn't match any theme, fall back to
[reflect, heartbeat](filtered against existence). - Validate every candidate — drop any skill where
skills/${skill}/SKILL.mddoesn't exist; log each drop asSPAWN_DROPPED_SKILL: ${skill}. - If the final list is empty (no content skills survive), exit
SPAWN_NO_SKILLS, notify, and stop.
Save the final list as SKILLS_ENABLED.
5. Fork the parent repo
First check whether the fork already exists:
gh api repos/<OWNER>/<REPO_NAME> --jq '.full_name'
If it prints the full name, FORK_STATE is exists; skip to the wait below. If it fails (404), try the modern flag first:
gh repo fork <PARENT_UPSTREAM> --fork-name <REPO_NAME> --clone=false
If that fails, fall back to a POST to /repos/{owner}/{repo}/forks with a custom name:
gh api repos/<PARENT_UPSTREAM>/forks -X POST -f name=<REPO_NAME> --jq '.full_name'
If that fails too, log SPAWN_FORK_FAILED and stop. Otherwise FORK_STATE is created.
Wait for fork availability (GitHub forks are async): run this check as a separate call, up to 10 times, until it prints the full name (each model turn between calls is the wait; there is no sleep):
gh api repos/<OWNER>/<REPO_NAME> --jq '.full_name'
If it still fails after 10 tries, log SPAWN_FORK_FAILED: fork not reachable after wait and stop.
6. Configure the fork
Work in the fixed directory /tmp/spawn-instance-work (the runner is thrown away after the run, so there is no cleanup step). Each line below is its own call:
mkdir -p /tmp/spawn-instance-work
gh repo clone <OWNER>/<REPO_NAME> /tmp/spawn-instance-work/repo -- --quiet
If the clone fails, log SPAWN_API_ERROR: clone failed and stop.
git -C /tmp/spawn-instance-work/repo config user.name "aeonframework"
git -C /tmp/spawn-instance-work/repo config user.email "aeonframework@proton.me"
Every path in 6a-6e (aeon.yml, SETUP.md, CLAUDE.md, memory/..., skills/...) is inside the clone, /tmp/spawn-instance-work/repo. Read and change those files with Read/Edit/Write on their absolute paths.
6a. Write a customized aeon.yml
- Read the parent
aeon.ymlas a base (preserves comments, ordering, and the full skill list). - Set
enabled: trueonly on skills inSKILLS_ENABLED. All others must haveenabled: false. - Do not drop any skills — keep the full inventory so the child can enable more later.
- Validate the result: every skill name with
enabled: truemust correspond to an existingskills/${skill}/SKILL.mdin the fork's tree. If any enabled skill is missing, abort before pushing (this is a sanity check — step 4 already validated, but the child's repo tree must match).
6b. Write SETUP.md dynamically
Parse each enabled skill's skills/${skill}/SKILL.md for references to uppercase env var names (pattern: [A-Z][A-Z0-9_]{2,}_(KEY|TOKEN|URL|ID|SECRET)). Collect the union across enabled skills, excluding built-ins (GITHUB_TOKEN, GH_TOKEN).
Emit a SETUP.md with three sections:
# Aeon Instance Setup
This is a managed Aeon instance spawned from `${PARENT_UPSTREAM}`.
## Purpose
${PURPOSE}
## Enabled Skills
${comma-separated list with one-line descriptions from each SKILL.md}
## Activate This Instance
Go to **Settings > Secrets and variables > Actions** and add these secrets:
### Required (pick one for Claude auth)
| Secret | Description |
|--------|------------|
| `ANTHROPIC_API_KEY` | Anthropic API key - console.anthropic.com |
| `CLAUDE_CODE_OAUTH_TOKEN` | Alternative: Claude Code OAuth token |
### Recommended (notifications)
| Secret | Description |
|--------|------------|
| `TELEGRAM_BOT_TOKEN` | Telegram bot token |
| `TELEGRAM_CHAT_ID` | Telegram chat ID |
| `DISCORD_WEBHOOK_URL` | Discord webhook URL |
| `SLACK_WEBHOOK_URL` | Slack webhook URL |
### Required by your enabled skills
${one row per detected env var, with the list of skills that reference it}
## Fleet Parent
Managed by `${PARENT_UPSTREAM}`. The parent can dispatch skills and monitor health via `fleet-control`.
## Security Note
This instance has NO access to the parent's secrets. Each instance maintains its own API keys and credentials.
If no env vars are detected beyond the required/recommended set, omit the "Required by your enabled skills" section header (don't leave an empty table).
6c. Update CLAUDE.md idempotently
Find the heading line ## About This Repo (or the first ## section if not present). Under it, insert exactly one line:
- Managed instance of ${PARENT_UPSTREAM}. Purpose: ${PURPOSE}.
If a line starting with - Managed instance of already exists, replace it rather than appending a duplicate.
6d. Reset child memory
The child starts with a clean slate:
- Reset
memory/MEMORY.mdto a minimal template with Write (PARENT_UPSTREAM and PURPOSE written in literally):# Long-term Memory *Last consolidated: never* ## About This Repo - Aeon instance of <PARENT_UPSTREAM>. Purpose: <PURPOSE>. ## Next Priorities - Configure secrets per SETUP.md - Wait for first scheduled skill to run - Clear logs, state and topics, safe paths only, never following symlinks, in one call: it deletes every regular file under
memory/logs,memory/topicsandmemory/issues(except files namedINDEX.md), and removesmemory/instances.json(the child has no fleet of its own). Missing directories are skipped:python3 -c 'import os; r="/tmp/spawn-instance-work/repo/memory"; [os.remove(p) for s in ("logs", "topics", "issues") for dp, _, fs in os.walk(os.path.join(r, s)) for f in fs for p in [os.path.join(dp, f)] if os.path.isfile(p) and not os.path.islink(p) and not (s == "issues" and f == "INDEX.md")]; j=os.path.join(r, "instances.json"); os.path.lexists(j) and os.remove(j)' - If
memory/issues/INDEX.mdexists (check with Glob), overwrite it with Write as the single line# Issues - none open. - Write
memory/cron-state.jsonas{}with Write.
6e. Commit and push
Each its own call, with PURPOSE, the skills list and PARENT_UPSTREAM written in literally:
git -C /tmp/spawn-instance-work/repo add -A
git -C /tmp/spawn-instance-work/repo commit -m "chore: configure instance - <PURPOSE>
Skills enabled: <SKILLS_ENABLED_CSV>
Parent: <PARENT_UPSTREAM>
Spawned: ${today}"
git -C /tmp/spawn-instance-work/repo push origin main
If that push fails, try:
git -C /tmp/spawn-instance-work/repo push origin HEAD:main
If that fails too, log SPAWN_PUSH_FAILED and stop.
If push fails, do not delete the fork — leave it for manual inspection and notify with:
spawn-instance: fork created but push failed for ${OWNER}/${REPO_NAME}.
Recover with: gh repo clone ${OWNER}/${REPO_NAME} && push manually, then re-register.
7. Enable GitHub Actions on the fork
Forks have Actions disabled by default. Use typed booleans (-F, not -f, or enabled=true is sent as the string "true"):
gh api repos/<OWNER>/<REPO_NAME>/actions/permissions -X PUT \
-F enabled=true -f allowed_actions=all
If it fails, log SPAWN_ACTIONS_FAILED and stop.
8. Post-flight verification
Three separate calls. Fork reachable:
gh api repos/<OWNER>/<REPO_NAME> --jq '.full_name'
If it fails, log SPAWN_API_ERROR: post-flight fork check failed and stop. Our commit is HEAD:
gh api repos/<OWNER>/<REPO_NAME>/commits/main --jq '.sha'
It prints HEAD_SHA. If it fails or prints nothing, log SPAWN_API_ERROR: post-flight HEAD check failed and stop. Actions enabled:
gh api repos/<OWNER>/<REPO_NAME>/actions/permissions --jq '.enabled'
If it does not print true, log SPAWN_ACTIONS_FAILED: post-flight and stop.
9. Register the instance
Update memory/instances.json in the parent repo. Append:
{
"name": "${NAME}",
"repo": "${OWNER}/${REPO_NAME}",
"purpose": "${PURPOSE}",
"created": "${today}",
"status": "pending_secrets",
"skills_enabled": ${SKILLS_ENABLED_JSON},
"parent": "${PARENT_UPSTREAM}"
}
If FORK_STATE == "exists" at step 5, the final exit status is SPAWN_FORK_EXISTS_RECOVERED, otherwise SPAWN_OK.
10. Log to memory
Append to memory/logs/${today}.md:
### spawn-instance
- Status: ${EXIT_CODE}
- Instance: ${OWNER}/${REPO_NAME}
- Purpose: ${PURPOSE}
- Skills: ${SKILLS_ENABLED_CSV}
- Dropped skills: ${DROPPED_CSV or "(none)"}
- Actions enabled: yes
11. Notify via ./notify
On success (SPAWN_OK or SPAWN_FORK_EXISTS_RECOVERED):
*New Aeon Instance*
Repo: ${OWNER}/${REPO_NAME}
Purpose: ${PURPOSE}
Skills (${N}): ${SKILLS_ENABLED_CSV}
Status: ${EXIT_CODE} - PENDING SECRETS
Activate:
1. https://github.com/${OWNER}/${REPO_NAME}/settings/secrets/actions
2. Add ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN)
3. Add TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID (or Discord/Slack)
See SETUP.md in the repo for the full secret list tailored to your enabled skills.
On refusal (SPAWN_FORK_EXISTS_REGISTERED, SPAWN_INVALID_VAR, SPAWN_NO_SKILLS):
spawn-instance: ${EXIT_CODE} - ${one-line reason}. No changes made.
On failure (SPAWN_FORK_FAILED, SPAWN_PUSH_FAILED, SPAWN_ACTIONS_FAILED, SPAWN_API_ERROR):
spawn-instance FAILED: ${EXIT_CODE}
Target: ${OWNER}/${REPO_NAME}
Recovery: ${one-line recovery instruction}
Network note
This skill runs entirely through gh CLI, which handles auth internally, so no bare $SECRET ever lands on the command line for the Bash permission layer to refuse. No WebFetch fallback needed. If gh is missing or unauthenticated, the pre-flight step fails with SPAWN_API_ERROR.
Constraints
- No secret propagation. Never read or write
ANTHROPIC_API_KEY,TELEGRAM_*,DISCORD_*,SLACK_*, or any API key into the child repo. The whole security model depends on this. - No hardcoded skill list. Always enumerate
skills/*/SKILL.mdat runtime to avoid referencing renamed or removed skills. - Idempotent. Re-running with the same
${var}must never produce duplicate registry entries, duplicate CLAUDE.md lines, or a second fork. - Never delete a fork. If anything fails partway through, leave the fork in place and emit recovery guidance — the operator is the only party authorized to delete it.
- Never push to the parent without committing
memory/instances.jsonvia the normal Aeon workflow. The parent commit happens through the same path as any other skill output.
Write complete, working code. No TODOs or placeholders.