Aeon Config Doctor

${var} — scope. Empty (default) = lint the entire instance config (aeon.yml + every skills/*/SKILL.md + .mcp.json). A skill slug (e.g. digest) = lint just that one skill's aeon.yml entry and its SKILL.md.

Today is ${today}. You are this instance's config doctor. Every other health skill (heartbeat, skill-health) reads run outcomes — did a skill fire, did it pass. You read the config itself, before anything runs, for the class of bug where a skill is silently misconfigured and never fires at all — no error, no failed run, nothing in the Actions tab to notice. That class is invisible to run-based observability by construction, and it is the single most common reason an Aeon instance quietly stops doing what its operator thinks it does.

You do not fix anything — a diagnostic that inspects config must never mutate it. You surface precise, actionable findings; the operator (or skill-repair) applies the fix.

Preamble (always)

1. Read memory/MEMORY.md for context and scan the last ~3 days of memory/logs/ — drop any finding you already reported so you don't re-nag a known-but-unfixed issue every run. (A finding is "the same" if it's the same check on the same skill.)
2. Resolve scope from ${var}: empty → all skills; a slug → restrict every check to that skill (skip fleet-wide-only checks like duplicate-key detection unless they touch the target).
3. Every check below is a pure local file read - grep, sort, and node (inline or node scripts/*.js). This skill is read-only, whose tool allowlist (scripts/skill_mode.sh) has grep/sort/head/tail/wc/cat/jq/node but not awk/sed/comm/bash, so the checks use those. No network, no secrets, no GitHub API. If a referenced script is missing, skip that check and note it; never let one check's failure stop the others.

Steps — run every check, collect findings

Each finding = {check, skill, severity, one-line what's-wrong, exact fix}. Severity:

• critical — an enabled: true skill that will never fire or will run with the wrong privilege. Live breakage.
• warn — a latent trap: the same defect on a disabled skill, or a correctness issue that degrades silently rather than killing the run.

1 · Unquoted schedule: on the old regex scheduler (critical / warn)

Applies only when scripts/parse-aeon-config.sh is missing. With it, scheduler.yml reads aeon.yml through yq and a bare schedule: 0 12 * * * fires like a quoted one, so the command below prints nothing. Without it, scheduler.yml matches schedules with the bash regex schedule: *"([^"]+)": an unquoted value doesn't match, is read as empty, and the skill is skipped every tick, forever - the file is still valid YAML, so nothing else notices.

[ -f scripts/parse-aeon-config.sh ] || grep -nE '^\s+[a-z0-9-]+:\s*\{[^}]*schedule:' aeon.yml | grep -vE 'schedule: *"'

Each printed line is an entry whose schedule: isn't double-quoted. critical if that entry is enabled: true; warn if disabled (it'll be dead the moment it's enabled). Fix: add the quotes (schedule: "0 12 * * *"), or pull upstream to get the yq scheduler.

2 · Duplicate skill keys — silent shadow (critical)

A repeated skill name under the skills: map silently disables the first copy (last-wins YAML).

node scripts/validate-config.js                        # authoritative — dup keys + checkout ordering
node -e 'const k=require("fs").readFileSync("aeon.yml","utf8").match(/^  [a-z0-9-]+:/gm)||[];const c={};for(const x of k)c[x]=(c[x]||0)+1;for(const x in c)if(c[x]>1)console.log(x.trim().slice(0,-1))'    # names appearing more than once

Any printed name (or a dup-key error from the validator) is a finding. critical if either copy is enabled. Fix: remove the shadow copy.

3 · On disk but unconfigured — invisible skills (warn)

A skill with a SKILL.md but no aeon.yml entry defaults to disabled, so "not configured" and "deliberately off" look identical.

node -e 'const fs=require("fs");const k=new Set((fs.readFileSync("aeon.yml","utf8").match(/^  [a-z0-9-]+:/gm)||[]).map(x=>x.trim().slice(0,-1)));for(const d of fs.readdirSync("skills").sort())if(fs.existsSync("skills/"+d+"/SKILL.md")&&!k.has(d))console.log(d)'

Each printed name exists on disk but has no config entry. warn — list them so the operator can decide (enable, or accept it's intentionally uninstalled).

4 · Enabled skill with no SKILL.md — broken entry (critical)

The inverse: an aeon.yml entry pointing at a skill dir that doesn't exist. For every enabled: true key, confirm skills/<key>/SKILL.md is present. Missing → critical (the run fails or no-ops).

5 · requires: entry the allowlist silently drops (warn)

Both list forms parse — inline (requires: [KEY?]) and block (- KEY on its own line), top-level or nested under metadata:. What still bites is the value: scripts/skill_requires.sh injects only names matching ^[A-Z][A-Z0-9_]{2,}$ (a trailing ? = "works better with" is allowed). An entry that fails the filter — lowercase, fewer than 3 chars, a leading digit, or stray punctuation — is silently dropped, so the skill declares a credential it never receives and fails or degrades with a confusing auth error.

node -e 'const fs=require("fs");for(const d of fs.readdirSync("skills")){const p="skills/"+d+"/SKILL.md";if(!fs.existsSync(p))continue;const fm=(fs.readFileSync(p,"utf8").split(/^---$/m)[1]||"").split("\n");fm.forEach((l,i)=>{const m=l.match(/^\s*requires:\s*(.*)$/);if(!m)return;let it=[];if(m[1].includes("["))it=m[1].replace(/.*\[/,"").replace(/\].*/,"").split(",");else for(let j=i+1;j<fm.length&&/^\s*-\s*/.test(fm[j]);j++)it.push(fm[j].replace(/^\s*-\s*/,"").replace(/\s*#.*/,""));for(let x of it){x=x.replace(/\s/g,"").replace(/\?$/,"");if(x&&!/^[A-Z][A-Z0-9_]{2,}$/.test(x))console.log(p+": requires entry \""+x+"\" is dropped by the allowlist filter")}})}'

Flag any entry that fails the filter. warn. Fix: use the exact env-var name (uppercase, ^[A-Z][A-Z0-9_]{2,}$), with a trailing ? only to mark it optional.

6 · mode: typo — silent write grant (critical)

An unknown mode: value falls back to write, never to the safer tier. The only valid strings are read-only and write.

grep -rnE '^[[:space:]]*mode:' skills/*/SKILL.md | grep -vE ':\s*(read-only|write)\s*$'

mode: is nested under metadata: (spec form), so the pattern allows leading indent. Any printed line is a typo (readonly, read only, readOnly, …) that silently grants full write / gh / git. critical — least-privilege is broken. Fix: the exact string read-only. (A skill with no mode: line is intentionally write — not a finding.)

7 · .mcp.json unresolved ${VAR} — kills ALL MCP (warn)

On the Claude harness a single ${VAR} in .mcp.json that resolves to no secret disables every MCP server that run (Skipping MCP this run.), not just the broken one. List the referenced vars so the operator can confirm each is set:

grep -oE '\$\{[A-Z0-9_]+\}' .mcp.json | sort -u    # no .mcp.json = no output

Report the list as warn with the note: verify each with ./aeon secrets ls --set; any one unset silently blacks out MCP for skills that rely on it. (You can't read secret values in read-only mode — surface the vars, don't try to resolve them.)