Scio

Scio is a per-project catalog of computational-biology skills, sub-agents, commands, CRAFT conventions, and executable guardrails for AI coding harnesses.

The toolkit keeps its mount sources in the same shape the harnesses consume: 85 skill directories, 21 flat agent files, and 7 flat command files. A project binds each category with one directory symlink.

Where this came from

The same needs kept recurring in every analysis project I worked in: a figure that stays legible whether it is shrunk into a journal column or projected to the back of a room, results that land where the next person looks for them, a caption written while the result is still fresh, a decision recorded before the next stage consumes it. I re-derived those conventions per project and lost them in between. They live here once now, and each project pins the version it was analysed with.

The road was bumpy. This began as a role-and-activation system that mounted curated subsets of a catalog and grew a manifest, a stack, a collision resolver and a provider-dispatch table on the way to 7,382 lines of Bash; measuring it showed the curation saved about 3% of a context window while breaking the routing graph between skills. What survives is three verbs over the catalog, one block of standing conventions, and a set of checks that run. The catalog was always the asset — the machinery around it was a long detour into finding that out.

Install

Most analysis of my projects started out vendoring this repository at 01_modules/scio/.

Use a relative alias so each project invokes its own pinned copy:

alias si='./01_modules/scio/bin/scio'

scio link refuses an external toolkit when the project contains its own scio checkout. This keeps the binding aligned with the project's submodule pin.

For one checkout, a PATH symlink is convenient:

ln -sf /absolute/path/to/scio/bin/scio ~/.local/bin/scio
scio --help

From a release tarball

The offline installer accepts a local release artifact and checksum. The release artifact is named scio; the installed command is scio.

./install.sh --archive  scio-0.1.0-<short-sha>.tar.gz \
             --checksum scio-0.1.0-<short-sha>.tar.gz.sha256 \
             --prefix   "$HOME/.local"

It installs a content-addressed version under ~/.local/share/scio/versions/<full-git-sha>/, links ~/.local/bin/scio, and writes a receipt. The installer has no network path. Maintainers build an artifact with scripts/build-release.sh <ref> from a clean tree.

Quick start

# Bind the catalog and materialize the project guardrail hooks.
scio link

# Render the shared computational-biology conventions into AGENTS.md.
scio craft

# Run project checks.
scio lint

Every verb accepting a project path defaults to the current directory:

scio link --project-dir /path/to/project
scio craft --project-dir /path/to/project
scio lint --project-dir /path/to/project

Verbs

Verb	Description
link [--project-dir D]	Bind the six catalog trees and ensure guardrail hooks
craft [--project-dir D] [--force] [--quiet]	Render or refresh SCIO:CRAFT in AGENTS.md
lint [--project-dir D] [--check <name>...] [--strict] [--quiet]	Run project guardrail checks

Run scio --help for the terse reference.

What link writes

project/
├── .claude/
│   ├── skills   -> <toolkit>/skills
│   ├── agents   -> <toolkit>/agents
│   ├── commands -> <toolkit>/commands
│   ├── settings.json
│   └── hooks/
│       ├── no_ephemeral.sh
│       └── caption_sweep.sh
└── .agents/
    ├── skills   -> <toolkit>/skills
    ├── agents   -> <toolkit>/agents
    └── commands -> <toolkit>/commands

link also refreshes the SCIO:GITIGNORE block in .gitignore.

link is convergent. A missing category link is created, a correct link is a silent no-op, and a link pointing elsewhere is replaced with a message. It also sweeps legacy toolkit-owned child mounts, retired output-style links, and dangling absolute mounts from older container paths.

A project may keep its own skills, agents, and commands in these six paths. When a category directory holds an entry the toolkit does not own, link preserves it and binds the catalog as one link per entry beside it instead of one link for the whole category. A project entry sharing a catalog entry's name is the one that loads, and link says so each run.

Hook bodies use a hash-and-cede ownership discipline. An unchanged body from any shipped toolkit version can be refreshed. A user-edited body is preserved, reported once, and ceded from future management. Hook registrations are merged into .claude/settings.json while unrelated project settings remain intact. On the first rebranded run, link moves .sciagent/ to .scio/ with its ownership hashes intact before inspecting any hook body.

Claude Code treats project settings as replacements for user settings except for permission rules. Scio writes only the two project guardrail hook registrations; editor, model, memory, attribution, thinking, and statusline preferences remain user-owned.

Manual removal

The deactivate verb has retired, so removing a project binding is manual. The catalog and managed context come out in two operations:

rm .claude/{skills,agents,commands} .agents/{skills,agents,commands}
# Edit AGENTS.md and remove the complete SCIO:CRAFT block.

One link per category makes the filesystem portion a single explicit rm line. The materialized hooks and their settings registrations remain project guardrails; remove those files and registrations separately when retiring the enforcement layer too.

Historical consumer repositories may still carry SCIAGENT:ROLES. The shipped block library reads and removes both SCIAGENT and SCIO marker prefixes:

TOOLKIT_PATH=/path/to/scio
bash -c '. "$1/lib/scio/block.sh"; block_remove "$2" ROLES' \
  _ "$TOOLKIT_PATH" /path/to/project/AGENTS.md

Validation and linting

scio lint --check toolkit checks every skill's name and description frontmatter. The name must match the directory and the description must fit the configured length cap. Cross-namespace collisions among skills, agents, and commands are warnings.

scio lint runs project checks for figure style, results layout, captions, provenance, freshness, stage structure, comment intent, documentation layout, and registered hook existence. Findings warn by default and become failures under --strict.

Harness support

Claude Code reads .claude/{skills,agents,commands}. Pi reads .agents/skills; extensions can consume .agents/agents and .agents/commands. Both trees point at the same toolkit sources.

Documentation

• Propagation model
• Architecture
• Skills catalog
• Agent catalog
• Command catalog