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 model | live composition via compose_inline, persisted as artifact lang_body, reopened with OpenArtifact | |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")

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?

Found a gap? Edit this file. <!-- footer-injection-point -->