# Skills — Workflow Guide

This directory contains life sciences **skills** in two flavors: **code-centric** (pipeline/toolkit/database) and **prose-centric** (guide).
This is the canonical guide used by coding agents to author new entries. `CLAUDE.md` is only a compatibility import shim; always update `AGENTS.md` when these instructions change.

## Directory Layout

```
├── AGENTS.md              ← you are here
├── registry.yaml          ← index of all entries
├── templates/
│   ├── SKILL_TEMPLATE.md          ← Pipeline-style skills (code-centric)
│   ├── SKILL_TEMPLATE_TOOLKIT.md  ← Toolkit-style skills (code-centric)
│   └── SKILL_TEMPLATE_PROSE.md    ← Guide-style skills (prose-centric)
├── legacy/                ← deprecated entries kept for historical reference;
│                            not in registry, not surfaced to agents
└── skills/                ← all entries (SKILL.md per entry)
    ├── molecular-biology/
    ├── genomics-bioinformatics/
    ├── proteomics-protein-engineering/
    ├── structural-biology-drug-discovery/
    ├── systems-biology-multiomics/
    ├── cell-biology/
    ├── medical-imaging/
    ├── biostatistics/
    ├── data-visualization/
    ├── lab-automation/
    ├── scientific-computing/
    └── scientific-writing/
```

---

## Workflow: Topic → Entry (5 Steps)

When given a topic (e.g., "CRISPR guide RNA design"), follow these steps:

> ## STOP — invoke the scaffolder first
>
> When the user asks to add a new SciAgent-Skills entry (any phrasing — "add a skill for X", "create a SciAgent skill", "scaffold X", "스킬 만들어줘", "신규 skill 추가"), the agent **MUST** invoke the `sciagent-skill-creator` skill via the Skill tool **before** writing any file or editing `registry.yaml`. Do not pattern-match on "add" and jump straight to manual authoring — that produces drift (missing tags, wrong path, malformed frontmatter, registry/disk mismatch).
>
> The scaffolder owns Steps 1, 2, 4, 5, and 6 (sub-type selection, category, template copy, registry append, validation). The numbered steps below explain *why* each field exists; the scaffolder is *how* you fill them. Use them together: read the rule, let the scaffolder enforce it.
>
> Only skip the scaffolder when (a) editing existing entry content, or (b) migrating an existing entry (see "Migrating from Existing Entries" below).

### Step 1. Classify — Code-centric vs Prose-centric, then Sub-type

#### 1a. Code-centric vs Prose-centric

All entries are Skills (SKILL.md). Choose the content style:

| Criteria | → Code-centric (pipeline/toolkit/database) | → Prose-centric (guide) |
|----------|---------------------------------------------|------------------------|
| Primary content | Executable code, pipelines, tool usage | Concepts, decision frameworks, best practices |
| Code blocks | 3+ substantial, runnable examples | Optional; illustrative only |
| User action | "Run this analysis" | "Understand this domain" |
| Example | "DESeq2 differential expression pipeline" | "When to use bulk vs single-cell RNA-seq" |

**Rule of thumb**: If the entry's core value is *running code*, it's code-centric. If it's *making informed decisions*, it's prose-centric (guide).

#### 1b. Sub-type

For code-centric entries, classify the sub-type (pipeline/toolkit/database). For prose-centric entries, the sub-type is always `guide`.

| Sub-type | Characteristics | Examples |
|----------|----------------|----------|
| **Pipeline** | Input→processing→output linear flow; one analysis process | scanpy, AutoDock Vina, DESeq2, STAR aligner |
| **Toolkit** | Collection of independent functional modules; multiple use-cases | RDKit, matplotlib, pandas, BioPython, scikit-learn |
| **Database** | API wrapper for external database queries; search/retrieve pattern | PubChem, KEGG, ChEMBL, UniProt, Ensembl via gget |

**Decision question**: "Can this tool be explained as **one pipeline** (load→process→output), does it require describing **multiple independent modules**, or is it primarily an **API/database accessor**?"

- One pipeline → **Pipeline** → use `templates/SKILL_TEMPLATE.md`
- Multiple modules → **Toolkit** → use `templates/SKILL_TEMPLATE_TOOLKIT.md`
- API/database queries → **Database** → use `templates/SKILL_TEMPLATE_TOOLKIT.md` with database adaptations
- Prose-centric guide → **Guide** → use `templates/SKILL_TEMPLATE_PROSE.md`

> **Type-specific adaptations** (Database, ML model, Model zoo, Platform integration, Non-Python, Visualization, Hardware/protocol, Data infrastructure, Document generation, Hybrid cases, Cross-cutting tools): see `references/tool-type-adaptations.md`

### Step 2. Choose Category

Pick the best-fit category directory under `skills/`:

| Category | Scope |
|----------|-------|
| `molecular-biology` | PCR, cloning, CRISPR, gene expression, central dogma, gene regulation |
| `genomics-bioinformatics` | NGS, alignment, variant calling, RNA-seq, genome architecture |
| `proteomics-protein-engineering` | Mass spec (proteomics AND metabolomics), protein design, structure prediction |
| `structural-biology-drug-discovery` | Docking, virtual screening, ADMET, drug design principles |
| `systems-biology-multiomics` | Pathway analysis, multi-omics integration, network biology |
| `cell-biology` | Cell-level microscopy, flow cytometry, cell culture analysis, particle tracking |
| `medical-imaging` | Clinical and radiology imaging: DICOM, WSI digital pathology, 3D volume registration, medical image segmentation, imaging archives |
| `biostatistics` | Statistical tests, experimental design, power analysis, study design |
| `data-visualization` | Plotting libraries, figure generation, scientific graphics |
| `lab-automation` | Robotics, LIMS, automated protocols |
| `scientific-computing` | General-purpose math/computation: symbolic math, numerical methods, MATLAB, data infrastructure, ML tools, geospatial, EDA, reproducibility |
| `scientific-writing` | Paper structure, figure design, peer review, research ideation and brainstorming, presentation skills |

**Cross-domain entries**: When an entry spans all scientific domains, place it in the category that best matches the entry's **primary audience**. Note the cross-domain nature in the description field. If no category fits well, prefer `scientific-computing` as the catch-all.

### Step 3. Gather Reference Material

Choose reference sources based on the entry type:

**For code-centric Skills** (primary — use these first):

| Source | When to use | URL pattern |
|--------|-------------|-------------|
| Official documentation | API reference, parameters, usage patterns | `{tool}.readthedocs.io`, `{tool}.org/docs/` |
| GitHub README / examples | Quick start, installation, version notes | `github.com/{org}/{tool}` |
| PyPI / conda-forge | Dependencies, version compatibility | `pypi.org/project/{tool}` |
| Published paper | Algorithms, citation, validation data | DOI link |
| Existing entry to migrate | Baseline for migration (see Migration section) | Local path |

**For wet-lab / protocol-heavy Skills** (secondary):

| Source | License | URL |
|--------|---------|-----|
| protocols.io | CC-BY | https://www.protocols.io/ |
| Bio-protocol | CC-BY | https://bio-protocol.org/ |
| OpenWetWare | CC-BY-SA | https://openwetware.org/ |
| STAR Protocols | CC-BY | https://star-protocols.cell.com/ |
| Galaxy Training | CC-BY | https://training.galaxyproject.org/ |
| Bioconductor workflows | Artistic-2.0 | https://bioconductor.org/packages/ |

**Rules**:
- Always cite the source in the References section
- Respect license terms (CC-BY requires attribution)
- Prefer peer-reviewed protocols and official docs over blog posts
- Adapt and synthesize; do NOT copy-paste verbatim

### Pre-Write Retention Budget Check (for migrations)

**Before writing ANY entry from an existing source**, determine whether you need reference files by performing this budget check:

1. **Calculate denominator**: Count original main file + ALL reference files total lines. Exclude `scripts/` and `assets/` directories.
2. **Estimate planned main file**: Decide if main SKILL.md will be 300–400 lines or 400–500 lines.
3. **Calculate aggregate retention**: If planned main ÷ original total < 0.45, you CANNOT go self-contained — you need reference files to reach 45–65% aggregate retention.
4. **Plan reference files BEFORE writing**: If aggregate < 0.45, calculate how many reference files you need. Work backward from the 50% target.
5. **Set per-reference-file line budgets**: Target `S × 0.40` lines (40% retention midpoint). For 2-source files, floor is `S × 0.35`; for 3+ source files, floor is `S × 0.30`. Write to the budget on first pass.

**Why this matters**: Authors often commit to "self-contained" consolidation without doing this math, then finish writing and discover they've dropped 20–30% of capabilities silently.

### Step 4. Author the Entry

Create the entry directory and file:

```
skills/{category}/{entry-name}/SKILL.md
```

**Entry name convention**: lowercase, hyphen-separated. Use `{tool-name}-{purpose}` format for clarity (e.g., `pydeseq2-differential-expression`, `scanpy-scrna-seq`).

Use the appropriate template:
- Code-centric (Pipeline) → `templates/SKILL_TEMPLATE.md`
- Code-centric (Toolkit) → `templates/SKILL_TEMPLATE_TOOLKIT.md`
- Prose-centric (Guide) → `templates/SKILL_TEMPLATE_PROSE.md`

#### Bundled resources: `references/`, `assets/`, `scripts/`

A SKILL.md is meant to be read top-to-bottom by an agent. When supporting material would balloon the main file or is better consumed as a standalone artifact, place it in a sibling directory next to SKILL.md:

| Directory | Use for | Examples |
|-----------|---------|----------|
| `references/` | Long-form prose, decision tables, theory notes, API cheatsheets that the agent should *read on demand*. Markdown only. | `references/theory.md`, `references/tile_extraction.md` |
| `assets/` | Static binary or copy-paste artifacts the agent should *use as-is*. | LaTeX style files, ICC color profiles, schema templates, sample input fixtures |
| `scripts/` | Runnable helper code that the agent should *execute or copy out wholesale*. Use when a code block exceeds ~80 lines, when the same boilerplate (`fetch_with_retry`, `download_to_tmp`, large CLI parsers) repeats across recipes, or when a self-contained CLI utility belongs to the entry. Python preferred; bash/R acceptable when matching the tool's native interface. | `scripts/scaffold.py`, `scripts/validate_description.py`, `scripts/batch_query.sh` |

When to extract code from SKILL.md into `scripts/`:
- The block is **>80 lines** and only ~5 lines of it carry teaching value
- The exact same helper repeats across multiple recipes
- The code defines a CLI tool the entry effectively *ships*
- Reproducibility hinges on the code running unchanged

When NOT to extract:
- The code is the lesson (showing `Chem.MolFromSmiles(s)` API usage is the point)
- The block is <30 lines
- Extraction would force a reader to switch files mid-thought

Scripts must be self-contained, runnable from the repo root, and include a docstring header (purpose + usage) so an agent can read the script as if it were a `references/` doc.

#### SKILL.md Format Rules — Pipeline Sub-type

For tools with a linear input→processing→output flow (e.g., scanpy, AutoDock Vina, DESeq2).

1. **Frontmatter** (YAML between `---`): `name`, `description`, `license` (all required)
   - **`license`**: Use the underlying tool's license if known. Default to `CC-BY-4.0` for original content
2. **Sections** (in order): Overview, When to Use (5+ items, user's task perspective), Prerequisites, **Pre-flight Interview** (analysis pipelines — see below), Quick Start (optional), Workflow (numbered steps, each with code block, 5-8 steps), Key Parameters (table), Key Concepts (optional), Common Recipes (2-4 snippets), Expected Outputs, Troubleshooting (table, 5+ rows), Bundled Resources (optional), References
3. **Code blocks**: **10+ total** (Prerequisites + Workflow + Recipes). Troubleshooting code excluded from count
4. **Description**: max 1024 characters, focused on "when should I use this?"
5. **Code quality**: all code blocks must be runnable as-is with sample data or clear placeholders. Include `print()` statements showing expected output shape/size
6. **Pre-flight Interview**: required for entries that run an analysis whose parameters change the scientific answer — see `## Pre-flight Interview` below for when it applies and the block schema

> **Bundled resources, Pipeline-with-variants details**: see `references/format-rules-detail.md`

#### SKILL.md Format Rules — Toolkit Sub-type

For tools that are collections of independent functional modules (e.g., RDKit, matplotlib, pandas, BioPython).

1. **Frontmatter** (YAML between `---`): `name`, `description`, `license` (all required)
2. **Sections** (in order): Overview, When to Use (5+ items, include 1-2 alternative tool comparisons), Prerequisites, Quick Start (recommended for 6+ modules), **Core API** (4-8 modules, each with 1-2 code blocks), **Key Concepts** (optional, for non-obvious data models and cross-cutting lookup tables), **Common Workflows** (2-4 end-to-end pipelines, at least 2 runnable), Key Parameters (table with Module column), **Best Practices** (optional, for large toolkits), Common Recipes (2-4 snippets), Troubleshooting (table, 5+ rows), Bundled Resources (optional), Related Skills (optional), References
3. **Code blocks**: **12 minimum** (4-5 modules) or **15+** (6+ modules). Count only Prerequisites, Core API, Common Workflows, Recipes
4. **Description**: max 1024 characters
5. **Code quality**: runnable as-is with sample data or clear placeholders
6. **Expected Outputs** section is **optional** for Toolkit skills
7. **Bundled resources**: same rules as Pipeline sub-type

> **Reference triage, CLI+Python dual interface, Related Skills, Ecosystem tools details**: see `references/format-rules-detail.md`

#### Guide SKILL.md Format Rules — Prose-centric

For entries where the core value is domain knowledge, decision frameworks, and best practices (sub_type: guide).

1. **Frontmatter** (YAML between `---`): `name`, `description`, `license` (all required)
2. **Sections** (in order): Overview, Key Concepts (3+ subsections), Decision Framework (ASCII tree + decision table), Best Practices (5+ items), Common Pitfalls (5+ items, each with "How to avoid"), Workflow (optional), Protocol Guidelines, Further Reading (3+ items), Related Skills
3. **Description**: max 1024 characters, focused on "when should I read this?"

> **Companion assets, bundled resources, adjacent domain content details**: see `references/format-rules-detail.md`

### Step 5. Update registry.yaml

Add the new entry to `registry.yaml`:

```yaml
entries:
  - name: "entry-name"
    type: skill
    sub_type: pipeline    # "pipeline", "toolkit", "database", or "guide"
    category: "genomics-bioinformatics"
    path: "skills/genomics-bioinformatics/entry-name/SKILL.md"
    description: "Brief description"
    date_added: "YYYY-MM-DD"
    tags: ["databases", "literature"]   # optional, see below
```

#### Description writing rules

The `description` field is the *only* hook an agent has when deciding whether to load the SKILL.md. Treat it as a search snippet, not a sentence.

- **Length**: 1024-character hard ceiling. Aim for the **first 120 characters** to be the carrier — tool name + domain + key outputs must all land in that window.
- **Lead with keywords, not stop verbs**: start with the tool name, library, or concept. Avoid `Use`, `Query`, `A`, `An`, `The` as the first word.
- **Disambiguation goes last**: cross-references like `For X use Y; for Z use W` belong at the end of the description, not the start.
- **Avoid promotional language**: no `powerful`, `comprehensive`, `state-of-the-art`. The reader is an LLM scoring relevance — adjectives waste tokens.

Anti-pattern → Fix:
- `Use the JASPAR REST API to query TF binding profiles...` → `JASPAR 2024 TF binding profile database via REST API and pyJASPAR. Retrieve PFMs/PWMs by TF name...`
- `An interactive visualization library...` → `Plotly interactive visualization. 40+ chart types (scatter, line, heatmap, 3D)...`

#### `tags` field (optional, cross-cutting discovery)

Use `tags` when an entry meaningfully belongs to more than one bucket but lives in a single `category` directory. Tags surface the entry under alternative lenses without duplicating the file.

When to use:
- Entry sits in one category but spans another (e.g., literature DB stored under `scientific-writing` deserves `["databases", "literature"]`)
- Cross-cutting concept that warrants discovery from multiple angles (e.g., ML libraries: `["machine-learning"]`)
- Future second-category lift (mark with a tag now, promote to a real category if the cluster grows)

When NOT to use:
- The entry has one obvious home and no meaningful secondary lens
- The "secondary" angle is just the description text (don't tag every genomics tool with `genomics`)

Conventions:
- Lowercase kebab-case (`machine-learning`, not `MachineLearning`)
- No duplicates within an entry
- Tags do **not** replace `category` — the primary home stays in `category`

Validator (`scripts/validate_registry.py`) enforces type, item type, kebab-case pattern, and uniqueness; missing tags is fine, malformed tags fails CI.

---

### Step 6. Validate

After creating or modifying an entry, run the test suite:

```bash
pixi run test
```

Tests verify registry integrity, frontmatter fields, required sections by sub-type, and content depth (code block counts, line counts). Fix any failures before finalizing.

For quick registry-only validation:

```bash
pixi run validate
```

---

## Pre-flight Interview

An agent running one of these entries writes the analysis code itself, so any
value it is not asked about it picks silently — and a wrong pick does not raise,
it answers a different question than the user asked (flip the reference level and
every fold change changes sign). This section declares what must be settled with
the user before any code is written.

`## Key Parameters` is not a substitute: the decisions that matter most are often
not function arguments at all ("which sample-sheet column separates the groups?"),
and it cannot mark which arguments to ask about. The consumer here is the
supervisor's plan gate (`workflow-delegation` in `hits-private-skills`), not a
human reader — hence YAML rather than this repo's usual table, and it is the
single authority: do not restate it as a prose table beside it.

**Required** for any entry that runs an analysis carrying at least one
parameter that changes the scientific conclusion, not just runtime or
formatting. This keys on what the entry *does*, not on its `sub_type`: a
toolkit whose modules carry real thresholds — a mapping-quality filter, a
required overlap fraction, a coverage normalization method — needs one as much
as a pipeline does, and a guide that describes a step which actually runs is
not exempt either.

For a toolkit, scope the block to the decisions that recur across its modules
and to those of the operations a pipeline actually calls — not one entry per
function. For a guide that frames choices without executing them, point at the
executing entry's block instead of duplicating it.

Not required for `database` entries, which return what the source holds, or for
entries whose every parameter is presentation. Say so in one line under the
heading rather than writing an empty block.

### Block schema

```yaml
decisions:
  - id: D2                 # unique within the entry
    param: contrast        # code symbol it binds; may repeat across decisions
    kind: required         # required | optional | optional_conditional | derived | never_ask
    source: user           # data | user | upstream | literature
    depends_on: [D1]       # optional - ids whose answers change THIS one's options
    ask: "Which group is the baseline the others are compared against?"
    default: "first level alphabetically"
    # skip_if: "..."       # optional - when the decision does not apply
    # reason: "..."        # required for never_ask
```

`ask` is phrased in biology terms, not parameter terms, and is required except
for `never_ask`. Use `default: null` when there is no safe default.

| `kind` | Behavior |
|---|---|
| `required` | Always ask — including confirm-questions where the agent inspected the data and proposes a value |
| `optional` | Silent default; ask on a user signal ("더 엄격하게", "clusters look too coarse") |
| `optional_conditional` | Silent default; ask when a stated trigger fires (unusual library prep, runtime blowup) |
| `derived` | Fixed by an upstream stage; apply it, confirm only on likely mismatch |
| `never_ask` | Cannot change the conclusion — threads, seeds, validated internals. Needs `reason` |

Thresholds, cutoffs, model formulas and normalization choices are never
`never_ask`, however standard their default.

| `source` | The agent gets the options by |
|---|---|
| `data` | Inspecting the input and offering what it found — sample-sheet columns, the levels in a column, an observed distribution |
| `user` | Asking outright; reflects study design, not recoverable from the files |
| `upstream` | Carrying it from the previous stage's output or settings |
| `literature` | A focused read-only lookup (genome build, established marker panel) |

`source: data` means inspect first — offering a guessed column name defeats it.

### `skip_if` vs. finding no candidates

`skip_if` is a condition on the **input** (`"single-end input"`) for decisions
that are meaningless there, such as paired-end adapter detection on single-end
reads. Drop the question and proceed.

A `source: data` inspection that finds **nothing** is the opposite and must not
be skipped: if no column groups the samples, the analysis cannot be specified at
all. Ask the user in plain text, or stop and report what is missing — never fall
back to a default or to whichever column comes first.

### `depends_on`

Tag an id only when its answer makes this decision's options *wrong*, not merely
unnecessary: choosing the grouping column is what makes the reference-level
options enumerable. Over-tagging splits the interview into one question per
round. The supervisor asks independent decisions together and defers dependent
ones to a later round. Refer only to ids in the same block; a value fixed by a
previous stage is `derived`, not a dependency.

---

## Quality Checklist

Before finalizing any entry, verify:

**Frontmatter:**
- [ ] Has `name`, `description`, `license` fields
- [ ] `description` ≤ 1024 characters
- [ ] `name` ≤ 64 characters
- [ ] `license` matches the underlying tool's license (or CC-BY-4.0 for original content)

**Structure:**
- [ ] All entries use SKILL.md filename
- [ ] Correct sub-type: Pipeline, Toolkit, Database (code-centric) or Guide (prose-centric) — see Step 1b
- [ ] All required sections present in correct order (see format rules above)
- [ ] Entry directory name is lowercase, hyphen-separated (`{tool-name}-{purpose}` preferred)

**Pipeline Skills — code depth:**
- [ ] Each Workflow step has its own code block (5-8 steps)
- [ ] Standard visualization included as Workflow steps, not Recipes
- [ ] Common Recipes has 2-4 self-contained snippets (alternative approaches, not workflow duplicates)
- [ ] Total code blocks ≥ 10
- [ ] Key Parameters table has 5+ rows with defaults and ranges
- [ ] Troubleshooting table has 5+ rows
- [ ] Quick Start section present (optional but strongly recommended)
- [ ] For Pipeline-with-variants: Key Concepts includes model/variant selection guide; Recipes cover each major variant

**Toolkit Skills — code depth:**
- [ ] Core API has 4-8 module subsections, each with 1-2 code blocks (8-16 total)
- [ ] Common Workflows has 2-4 complete end-to-end examples
- [ ] Common Recipes section has 2-4 self-contained snippets
- [ ] Total code blocks ≥ 12 (4-5 modules) or ≥ 15 (6+ modules)
- [ ] Key Parameters table has 5+ rows with defaults and ranges
- [ ] Troubleshooting table has 5+ rows

**Toolkit Skills — content quality:**
- [ ] "When to Use" includes 1-2 alternative tool comparisons
- [ ] Common Workflows combine multiple Core API modules
- [ ] Key Parameters table has Module/Function column for multi-module tools
- [ ] Best Practices section present for large toolkits
- [ ] Related Skills section present for ecosystem tools
- [ ] Ecosystem Integration shown via code snippets if tool is part of a larger ecosystem

**Guide Skills — content depth:**
- [ ] Key Concepts has 3+ subsections with clear definitions
- [ ] Decision Framework includes both ASCII tree diagram AND decision table
- [ ] Best Practices has 5+ items with rationale
- [ ] Common Pitfalls has 5+ items, each with "How to avoid" sub-item
- [ ] Workflow section present if the guide has a clear sequential process
- [ ] **Main SKILL.md is 250+ lines** (for originals with 2,000+ total lines, target 350-400 lines)

**Content quality (all types):**
- [ ] "When to Use" items written from user's task perspective, not keyword-matching
- [ ] References cite sources with URLs (3+ references)
- [ ] Code blocks are runnable as-is (with sample data or clear placeholders)
- [ ] **Code verification**: spot-check at least 2 code blocks — verify function signatures, argument names, return types against official docs
- [ ] **Cross-file consistency**: code examples in SKILL.md and `references/` use consistent API patterns
- [ ] **URL verification**: spot-check primary URLs against official project. Do NOT invent repository URLs
- [ ] No verbatim copy-paste from sources (synthesize and attribute)
- [ ] No promotional or advertising content
- [ ] **Check-before-install**: Prerequisites sections for CLI executables include a note telling the agent to run `command -v <tool>` first and skip the install commands if the tool is already present (e.g., inside a `pixi` / `conda` env), and to invoke tools via `pixi run <tool>` when inside a pixi project
- [ ] `registry.yaml` updated with new entry
- [ ] Description leads with tool/domain keyword in the first 120 characters (no stop-verb start)
- [ ] Cross-cutting entries: `tags` field set in registry (kebab-case list); description still leads with the primary lens
- [ ] Bundled code: only inline blocks <80 lines OR repeating boilerplate; longer/repeated helpers live in `scripts/`
- [ ] No duplicate of an existing entry: `grep -i <topic>` on `registry.yaml` and `legacy/` before authoring
- [ ] (migrations) Capability completeness, pitfall migration, narrative use-case disposition, stub detection checks completed

> **Type-specific additional checks** (Database, ML model, Platform, Visualization, Hardware, Data infra, Model zoo, Document generation, Guide migration, Migration quality): see `references/quality-checklist-by-type.md`

---

## Category Hygiene

The category list is intentionally short. Two operational rules keep it that way:

### When to split a category

A category becomes harmful when its name no longer predicts what lives inside. Signals to split:

- **Size**: 50+ entries and growing — agents start scanning irrelevant entries during discovery
- **Cluster mixture**: more than ~3 distinct sub-clusters share one directory (e.g., `cell-biology` once held cell microscopy + DICOM + WSI + flow cytometry — four clusters under one name)
- **Description drift**: new entries land with descriptions that need to disambiguate "this isn't actually about X" against the category name

Process when splitting:
1. Propose the new category (name + scope) in an issue or RFC PR
2. List every entry that moves, with reasoning
3. Update the **category table in Step 2** of this file
4. Move entries via `git mv` so history is preserved; update `category` and `path` in `registry.yaml`
5. Refresh cross-references in other SKILL.md files
6. Run `pixi run test` — `test_category_matches_directory` and `test_path_matches_category` catch most slip-ups

### Sub-clustering large categories (genomics-bioinformatics)

When a category is genuinely cohesive but oversized (`genomics-bioinformatics` sits at 60+ entries), consider an internal sub-cluster directory layer:

```
skills/genomics-bioinformatics/
  databases/        ← *-database entries
  alignment/        ← aligners, BAM/SAM tooling
  single-cell/      ← scRNA/scATAC pipelines
  variant/          ← variant calling, annotation, GWAS
  rnaseq/           ← bulk RNA-seq counting + DE
  annotation/       ← prokka, bakta, ensembl-style
  ...
```

Rules if introducing sub-clusters:
- `registry.yaml` `category` field stays at the top-level name (`genomics-bioinformatics`) — sub-clusters are filesystem-only
- Update `path` to include the sub-cluster directory
- Run the schema tests; the path/category check uses the *first* path segment under `skills/`
- Don't sub-cluster categories under 20 entries — the directory hop is friction without payoff

This is the only place internal hierarchy is allowed below `skills/{category}/`.

---

## Migrating from Existing Entries

When creating an entry for a topic that already has an existing version to migrate from:

1. **Read the original** as reference material (Step 3), but author a fresh entry following the template — do NOT copy-paste the original's structure
2. **Re-classify**: The original may be code-centric but could be better suited as a prose-centric guide. Always re-evaluate with Step 1 criteria
3. **Bundled resources and assets**:
   - If the original has `references/` files, create new ones adapted to the template format, or omit them if the SKILL.md is self-contained enough
   - If the original has `assets/` (templates, style files): for **Guide** entries, always create a `Companion Assets` section and migrate relevant templates. For code-centric entries, evaluate whether to include as `references/` or omit
   - If the original has `scripts/` (helper Python code): incorporate key script functionality into Core API or Common Recipes code blocks
3b. **Non-markdown reference files** (YAML configs, JSON schemas, INI templates, CSV templates): Consolidate inline if under ~100 useful lines; preserve as `references/` files if they serve as copy-paste templates
4. **Strip promotional content and agent meta-instructions**: Remove advertising, platform promotion, vendor-specific sections, and agent-behavior sections. Skills should contain tool knowledge, not agent prompting
5. **Capability completeness check**: Before writing, list every distinct capability/function in the original (including all reference files). After writing, verify each has a home in the new entry or is documented as intentionally omitted
6. **Improve on weaknesses**: Common issues include missing Key Parameters tables, free-form Troubleshooting, absent Expected Outputs sections, no Best Practices for Toolkits, "When to Use" written from keyword-matching perspective
7. **Keep the strengths**: If the original has deeper content, incorporate that depth into the appropriate template section
7a. **API modernization**: Update outdated API patterns to current conventions. Note the modernization in Bundled Resources
7b. **Narrative use-case sections**: Consolidate "Common Use Cases" etc. into "When to Use" bullets and "Common Workflows". Per-use-case disposition required

> **Extended migration rules** (Rule 5b per-reference-file disposition, Rules 8-13 for long originals/stubs/Guide migrations/omissions, Transformation Migrations, Emergency Recovery): see `references/migration-rules.md`

---

## Progressive Disclosure Integration

All SKILL.md entries follow the same **progressive disclosure** pattern:

1. **Prompt injection**: Only `name` + `description` from frontmatter are injected into the agent's system prompt
2. **On-demand reading**: When the agent decides a skill is relevant, it reads the full file via `read_file`
3. **This keeps prompts lean** while giving agents access to deep domain knowledge