Skills-first architecture — operational quickstart

A 5-minute onboarding for an operator (or new agent) coming cold to the SciDEX skills-first architecture. Covers: what to read first, what to run, what to expect. Companion to:

SPEC-199 norm — the architectural rules.
Session retrospective — narrative of how it was built.
Methodology cluster index — reading guide for the 11-node meta-science content cluster.
Cortical mini-cluster index — parallel 5-artifact Allen Institute domain-diversifying cluster (iter-101 → iter-106). Demonstrates the authoring discipline transferring to cortical neurobiology.

TL;DR — what exists

Layer	Where	Count
Substrate skills	`scidex-substrate/skills/<name>/SKILL.md`	~63
Agents-side skills	`scidex-agents/skills/<name>/SKILL.md`	~25
Authoring skills	6 (wiki/hypothesis/analysis/mission/benchmark + skill-authoring META)	all with EXAMPLES
Methodology content cluster	`scidex-substrate/skills//EXAMPLES/.md`	11 nodes
Personas	`scidex-agents/personas/*.json`	16 (10 mission-scientists + 6 governance)
Cross-repo CI guards	`tests/unit/test_*.py` (substrate + agents)	15 (38 tests; verified iter-186)
Operator tools	substrate `scripts/` + scidex-agents `tools/`	5

5-tool operator pack — run these in order

For a quick health check of the architecture:

# 1. WHAT skills exist + their structure (substrate-side):
python3 scidex-substrate/scripts/skills_coverage_report.py | head -50

# 2. WHO owns what maintenance (persona × skill aggregate):
python3 scidex-agents/tools/maintenance_coverage_report.py | head -40

# 3. WHAT would a specific persona run this cycle (e.g. governance):
python3 scidex-agents/tools/persona_runtime_simulator.py ibn-al-haytham-governance

# 4. IS the methodology content cluster healthy:
python3 scidex-substrate/scripts/methodology_cluster_smoke.py
#    Or — inverse-direction query: "which other cluster nodes link
#    to this one?" (iter-93 #2155 deprecation-impact mode):
python3 scidex-substrate/scripts/methodology_cluster_smoke.py --incoming-refs pre-registration

# 5. WHO calls a specific substrate verb (deprecation impact):
python3 scidex-substrate/scripts/verb_persona_traceback.py scidex.economics.transfer

Each tool is pure-FS; no DB or LLM required. Each documents itself via --help. Exit code 0 = clean; non-zero = findings.

Stale-checkout caveat (iter-64 / iter-73 / iter-86 finding): the agents-side tools read persona JSONs from the local /home/ubuntu/scidex-agents/personas/ checkout. If LOCAL main lags origin/main, results undercount. Run git fetch + checkout origin/main first when working from a fresh shell.

15 CI guards — what’s enforced at PR-time

Every PR runs:

Guard	Catches
`test_skills_verb_references`	Skill body cites non-existent `scidex.<verb>`
`test_skill_body_length_cap`	Body exceeds 6000-char runtime cap
`test_no_orphan_system_prompts`	`_SYSTEM_PROMPT` defined but never wired to LLMRequest
`test_skill_dependency_refs`	`dependencies.skills` entry doesn’t resolve
`test_skill_lifecycle_state`	Missing or invalid `lifecycle_state` (substrate)
`test_no_cross_repo_skill_load`	`load_skill_body("scidex-...")` called from substrate (cross-loader truncation)
`test_methodology_cluster_integrity`	Cluster cross-ref drift / PMID drift / node-count mismatch
`test_skill_body_loaded_when_inline_prompt_used`	Inline `_SYSTEM_PROMPT` passed as `system=` without `load_skill_body` fallback (iter-115)
`test_skill_cross_references_present`	Non-legacy substrate skill missing `## Cross-references` (iter-125)
`test_authoring_skills_have_examples`	User-facing authoring skill missing ≥1 `EXAMPLES/*.md` (iter-126)
`test_skills_personas_consistency` (agents)	Persona pins non-existent skill
`test_persona_permission_policy` (agents)	Mission-scientist pins governance/economics skill
`test_maintenance_coverage_doc_vs_pins` (agents)	MAINTENANCE-COVERAGE doc row drifts from JSON pins (iter-124)
`test_agents_skills_cross_references` (agents)	Agents-side skill missing `## Cross-references` (iter-133)
`test_agents_skills_lifecycle_state` (agents)	Agents-side skill missing/invalid `lifecycle_state` (iter-135)

All exception lists are currently empty (clean state) except _LEGACY_GRANDFATHERED (27 v1 snake_case domain ports exempt from the cross-refs guard per doctrine).

Common questions

“I want to add a new substrate skill.” Read skills/skill-authoring/SKILL.md + walk through skills/skill-authoring/EXAMPLES/authoring-benchmark-authoring.md for the 7-step authoring discipline.

“I want to add a new persona.” Read scidex-agents/skills/persona-creation/SKILL.md (the persona- creation skill, iter-61 of the 2026-05-22 pre-session). Then update scidex-agents/skills/MAINTENANCE-COVERAGE.md if the persona has maintenance responsibilities.

“I want to deprecate a substrate verb.” Run verb_persona_traceback.py <verb> to find the personas whose pinned skills reference it. Coordinate the deprecation with those personas’ maintainers.

“What’s the cluster? What’s a ‘methodology node’?” Read skills/METHODOLOGY-CLUSTER.md — 11-node index showing topology, node table, and 3 recommended reading orders for different newcomer goals.

“What does Wave-3 / Wave-4 status mean?” Read SPEC-199 §4.2 + §6 for the catalogs. Wave-4 has its own operator-facing gate-status doc at scidex-agents/docs/wave-4-seed-corpus-gate-status.md (iter-70 #80) — 0 of 4 preconditions met; deferral honest.

Common operator tasks

Task	Tool / doc
“What does this persona run each cycle?”	`persona_runtime_simulator.py <binding_id>`
“What verbs does my new skill need to reference?”	grep substrate `src/scidex_substrate/skill/verbs/*.py` for `@verb(name=...)`
“Is my new skill body too long?”	`test_skill_body_length_cap` (CI) + check via `load_skill_body`
“Did I forget the lifecycle_state field?”	`test_skill_lifecycle_state` (CI)
“Is my new content cluster exemplar cross-linked?”	`methodology_cluster_smoke.py` (CI guard #2148)
“Before renaming/removing a cluster node, what links break?”	`methodology_cluster_smoke.py --incoming-refs <slug>` (iter-93 #2155)
“Should an Allen Institute scientist pin this skill?”	`test_persona_permission_policy` (CI) catches scientists pinning governance/economics
“How do I author a benchmark/mission/etc.?”	`skills/<artifact>-authoring/SKILL.md` + its EXAMPLES
“Did I forget `## Cross-references` on my new skill?”	`test_skill_cross_references_present` (CI iter-125 substrate) / `test_agents_skills_cross_references` (iter-133 agents)
“Did I forget `EXAMPLES/` on a new user-facing authoring skill?”	`test_authoring_skills_have_examples` (CI iter-126)
“Did I inline `_SYSTEM_PROMPT` without `load_skill_body` fallback?”	`test_skill_body_loaded_when_inline_prompt_used` (CI iter-115)
“Did I forget `lifecycle_state` on a new agents-side skill?”	`test_agents_skills_lifecycle_state` (CI iter-135)
“Did MAINTENANCE-COVERAGE doc drift from persona JSON pins?”	`test_maintenance_coverage_doc_vs_pins` (CI iter-124)

Where everything lives

/home/ubuntu/
├── scidex-substrate/
│   ├── docs/
│   │   ├── design/spec-199-skill-first-architecture.md  ← norm
│   │   ├── sessions/2026-05-22-skills-first-migration.md ← retrospective
│   │   └── operations/skills-first-quickstart.md         ← THIS DOC
│   ├── skills/
│   │   ├── METHODOLOGY-CLUSTER.md                       ← methodology cluster index (11 nodes)
│   │   ├── CORTICAL-CELL-TYPE-CLUSTER.md                ← cortical mini-cluster index (5 nodes; iter-106)
│   │   ├── <skill-name>/SKILL.md                        ← per-skill bodies
│   │   └── <authoring-skill>/EXAMPLES/                  ← worked examples
│   ├── scripts/
│   │   ├── skills_coverage_report.py                    ← tool 1
│   │   ├── methodology_cluster_smoke.py                 ← tool 4
│   │   └── verb_persona_traceback.py                    ← tool 5
│   └── tests/unit/test_*.py                             ← 7 substrate CI guards
└── scidex-agents/
    ├── docs/
    │   ├── wave-4-seed-corpus-gate-status.md            ← Wave-4 gate
    │   └── (other agent docs)
    ├── personas/<binding_id>.json                       ← 16 personas
    ├── skills/
    │   ├── MAINTENANCE-COVERAGE.md                      ← persona×skill policy
    │   └── scidex-*/SKILL.md                            ← 17 operational skills
    ├── tools/
    │   ├── maintenance_coverage_report.py               ← tool 2
    │   └── persona_runtime_simulator.py                 ← tool 3
    └── tests/test_*.py                                  ← 2 agents-side CI guards

Cross-references

SPEC-199
Session retrospective
Methodology cluster index
Cortical mini-cluster index — domain-diversifying parallel cluster (Allen Institute domain)
Wave-4 gate-status
Maintenance coverage policy