brain-capabilities

Deterministic scanner that surfaces "what can this brain do RIGHT NOW" as a machine-readable log + a human-readable wiki page. The Brain view reads state/log/capabilities.ndjson directly; humans read state/docs/brain-capabilities.md.

Produces one row per skill with {ts, skill, description, graduation, verb_family, sample_input, sample_output_hint, runs_7d, mean_score_7d, last_run_ts}. No LLM calls -- pure read + static keyword classifier + append.

When it runs

• Daily at 05:00 local via claude-cron.sh brain-capabilities (cron entry

runs this skill's prompt file which is this very page).

• On-demand when you add a new skill, want the Brain view to reflect it,

or want to refresh the 7d eval window.

Usage

npx tsx state/bin/brain/capabilities.ts            # write ndjson only
npx tsx state/bin/brain/capabilities.ts --markdown # write ndjson + wiki md

Steps

1. Scope (read-only)

Read state/skills/*.md, skipping _template.md and *AGENTS.md loader sidecars. Parse frontmatter (name, description, graduation, re_test_input). Read state/log/evals.ndjson, filter to rows within the last 7 days, group by skill || verb (old rows used verb, new rows use skill).

2. Classify

For each skill, apply the static keyword classifier (CLASSIFIERS in the script). First match wins. The 11 families: image, email_draft, meeting_action, browse_web, memory_ops, code_gen, schedule, compute, audit, publish, unclassified. Order matters; more specific signals are listed first.

3. Emit

Append one line per skill to state/log/capabilities.ndjson via state/lib/log.ts::append(). With --markdown, also rewrite state/docs/brain-capabilities.md grouped by verb_family.

4. Eval

Shape gate only. Pass = wrote N ndjson rows where N equals the count of non-template, non-sidecar skills in state/skills/. Fail = mismatch or exception. Manual spot-check for classifier accuracy lives in state/log/pending-eval.ndjson and is refined by adding keywords to CLASSIFIERS when the unclassified bucket grows.

Eval

Actor: the capabilities.ts scanner (writes the ndjson). Auditor: the skill-count check -- wc -l state/log/capabilities.ndjson grows by exactly the number of skills scanned per run. Mismatch = 0.0, exact match = 1.0. Independent because the count comes from a different codepath (readdirSync filter) than the writer (append loop).

const files = readdirSync(SKILLS_DIR)
  .filter(f => f.endsWith(".md") && f !== "_template.md" && !f.endsWith("AGENTS.md"));
const before = countLines("state/log/capabilities.ndjson");
// ... run scanner ...
const after = countLines("state/log/capabilities.ndjson");
const ok = (after - before) === files.length;
score("brain-capabilities", run_id, { score: ok ? 1.0 : 0.0, skills: files.length });

Gotchas

• Old eval rows use verb, newer rows use skill. Both must be keyed

into the same lookup map.

• state/skills/*AGENTS.md are loader sidecars, not skills -- always skip.
• _template.md is a scaffolding source; never emit it as a capability.
• The classifier is a static keyword map, not an LLM. Growing the

unclassified bucket is a signal to extend CLASSIFIERS, not to call a model.

• sample_input pulls from re_test_input frontmatter first, then falls

back to the first fenced code block. Empty string is a valid value and means "no documented sample."

• Brain view (Pod 24) reads the LATEST ts-group in

state/log/capabilities.ndjson. Append-only log is correct -- callers take the tail, not a snapshot file.

Graduation

Graduated. The script at state/bin/brain/capabilities.ts is the deterministic path. This page exists to document intent and the eval. If the agent needs to regenerate the logic, it reads this page + the script.

Rubric

criteria:
  - name: ndjson_row_count_matches_skills
    kind: deterministic
    check: "The difference between `wc -l state/log/capabilities.ndjson` before and after the script run must equal the count of non-template, non-sidecar skill markdown files in `state/skills/`."
  - name: capabilities_ndjson_integrity
    kind: deterministic
    check: "Each line appended to `state/log/capabilities.ndjson` must be valid JSON and contain the specified fields: `ts`, `skill`, `description`, `graduation`, `verb_family`, `sample_input`, `sample_output_hint`, `runs_7d`, `mean_score_7d`, `last_run_ts`."
  - name: markdown_update_correctness
    kind: judge
    check: "If the `--markdown` flag is used, `state/docs/brain-capabilities.md` must be rewritten correctly with capabilities grouped by `verb_family` and reflect the current capabilities data."
  - name: classifier_accuracy
    kind: judge
    check: "The `verb_family` assigned to each skill in the generated `capabilities.ndjson` should accurately reflect the skill's primary function based on the static keyword classifier, minimizing 'unclassified' for known types."

brain-capabilities - loader

Per-turn rules. Full reference: state/skills/brain-capabilities/SKILL.md. Do not skip these.

Critical Rules

• ALWAYS run the script; NEVER hand-build the catalog. The Brain view expects state/log/capabilities.ndjson written by capabilities.ts.
• NEVER include _template.md or any */AGENTS.md loader in the catalog. Those are scaffolding, not skills.
• Classifier is a static keyword map. If unclassified grows, edit CLASSIFIERS in state/bin/brain/capabilities.ts -- never reach for an LLM.
• The log is append-only. Do NOT truncate state/log/capabilities.ndjson; downstream readers take the latest ts-group.
• Old eval rows use verb, newer rows use skill. Both must contribute to 7d stats.

Commands

| ui dashboard | state/skills/brain-capabilities/resources/ui.openui | |invoke: npx tsx state/bin/brain/capabilities.ts --markdown |verify: wc -l state/log/capabilities.ndjson grew by N where N = skills scanned; state/docs/brain-capabilities.md header shows current ts |eval log: state/log/evals.ndjson (auto-shape -- skill: "brain-capabilities")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/brain-capabilities/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Frontmatter parser is scalar-only; nested inputs: children are intentionally ignored.
• sample_input falls back to first fenced code block. Empty is valid.
• Running without --markdown only writes ndjson, which is what Pod 24's Brain view wants. Use the flag for the human wiki page.

Self-Test

1. [ ] Skipped _template.md and all */AGENTS.md?
2. [ ] Appended rather than truncated capabilities.ndjson?
3. [ ] Extended CLASSIFIERS instead of calling an LLM when unclassified grew?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] brain-capabilities: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] brain-capabilities: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.