Summary
Add more Agent Skills under .claude/skills/ to give LLM agents on-demand, domain-specific guidance for the most common ConfUSIus development tasks.
Background
ConfUSIus already has a .claude/skills/release/SKILL.md skill (correctly flagged disable-model-invocation: true since it's irreversible). Skills follow the open Agent Skills standard — a SKILL.md file with YAML frontmatter (required: name, description) plus optional scripts/, references/, assets/. The description field is loaded into every conversation at startup, so it must be specific and include trigger keywords. The body is loaded on demand (progressive disclosure).
Adopted by Claude Code, Codex, Gemini CLI, Cursor, Copilot, Goose, and 30+ other tools.
Proposal
Add three skills (gerund-form naming per Anthropic convention, no disable-model-invocation flag — they should be discoverable):
-
.claude/skills/processing-iq/SKILL.md — canonical data flow for adding a new IQ-processing step
IQDataArray → which _utils module → which public module → docstring patterns → test fixtures
- Pointers to
docs/user-guide/beamformed-iq.md, docs/api/iq.md, src/confusius/iq/
-
.claude/skills/adding-examples/SKILL.md — adding a new example to the gallery
- Jupytext format (
# %% [markdown] headers)
- Directory convention under
docs/examples/
- Nav update in
zensical.toml
tools/build_gallery.py discovery
- Light/dark output-parity rule
tools/prefetch_doc_datasets.py cache update
-
.claude/skills/working-with-fusi-bids/SKILL.md — working with the fUSI-BIDS layout
- Layout spec, validation module, loader patterns
- Pointers to the fusi-bids example
Optional follow-ups
- Trim the corresponding sections out of
AGENTS.md once skills exist (progressive disclosure — AGENTS.md stays high-level, skills carry the detail)
- Use the
release skill as the template for SKILL.md structure and frontmatter
Why
- The current
AGENTS.md is comprehensive (338 lines) but everything sits in one file. Skills let agents load domain knowledge on demand without bloating the always-loaded context.
- Each skill is one PR, ~1 day, low risk.
- Demonstrates the pattern for future contributors.
Effort
Low–medium per skill. Can be shipped as one PR with all three, or split.
Summary
Add more Agent Skills under
.claude/skills/to give LLM agents on-demand, domain-specific guidance for the most common ConfUSIus development tasks.Background
ConfUSIus already has a
.claude/skills/release/SKILL.mdskill (correctly flaggeddisable-model-invocation: truesince it's irreversible). Skills follow the open Agent Skills standard — aSKILL.mdfile with YAML frontmatter (required:name,description) plus optionalscripts/,references/,assets/. Thedescriptionfield is loaded into every conversation at startup, so it must be specific and include trigger keywords. The body is loaded on demand (progressive disclosure).Adopted by Claude Code, Codex, Gemini CLI, Cursor, Copilot, Goose, and 30+ other tools.
Proposal
Add three skills (gerund-form naming per Anthropic convention, no
disable-model-invocationflag — they should be discoverable):.claude/skills/processing-iq/SKILL.md— canonical data flow for adding a new IQ-processing stepIQDataArray→ which_utilsmodule → which public module → docstring patterns → test fixturesdocs/user-guide/beamformed-iq.md,docs/api/iq.md,src/confusius/iq/.claude/skills/adding-examples/SKILL.md— adding a new example to the gallery# %% [markdown]headers)docs/examples/zensical.tomltools/build_gallery.pydiscoverytools/prefetch_doc_datasets.pycache update.claude/skills/working-with-fusi-bids/SKILL.md— working with the fUSI-BIDS layoutOptional follow-ups
AGENTS.mdonce skills exist (progressive disclosure —AGENTS.mdstays high-level, skills carry the detail)releaseskill as the template for SKILL.md structure and frontmatterWhy
AGENTS.mdis comprehensive (338 lines) but everything sits in one file. Skills let agents load domain knowledge on demand without bloating the always-loaded context.Effort
Low–medium per skill. Can be shipped as one PR with all three, or split.