---
description: |
  [TOPIC] Skills Overview
  [DETAILS] Practical author's guide for writing and maintaining `_skills/` content in every SciTeX package — what a "skill" is in the Claude Code sense (an agent-loadable rule file, not a dev doc), the SKILL.md-as-index pattern, leaf-file scope (one topic per `.md`), prose over checkboxes, lessons from past audits (audit-driven remediation), and the authoring workflow from idea → draft → export → commit. Use when writing any new skill or overhauling an existing one.
tags: [scitex-general-interface-skills-overview]
---

# Writing Skills for SciTeX Packages

Skills are agent-loadable rule files — distinct from developer-facing READMEs or Sphinx docs. The Claude Code runtime reads frontmatter `description` and `tags` to decide whether to auto-load a file.

This document is the **ecosystem-wide convention** for the Skills interface. Rules below are abstracted from convergence across the ~67 packages registered in `scitex_dev.ecosystem.ECOSYSTEM` — wherever a majority of packages already do the same thing, that is documented here as the rule. Outliers (e.g., `scitex-notification` unprefixed leaves, `scitex-tunnel` missing `_skills/`) are tracked in [TODO.md](TODO.md) as standardization items, not as alternative styles.

## Workflow

Source of truth lives in the package source. Dotfiles / `~/.claude/skills/scitex/` copies are **auto-generated exports** — never edit them directly (a pre-tool-use hook blocks such edits).

```bash
# 1. Investigate the codebase first
#    Read _builtin_handlers.py, __init__.py, _save.py — not just README
#    Claims in docs must match actual registered handlers

# 2. Edit in the package source (single source of truth)
vi ~/proj/<repo>/src/<pkg>/_skills/<pip-name>/<file>.md

# 3. Export to ~/.claude/skills/scitex/<pip-name>/
scitex-dev skills export --package <pip-name>
```

Do NOT add `[tool.hatch.build.targets.wheel.force-include]` for `_skills/` — hatch already includes files under `src/<pkg>/` in the wheel. See [07_registration.md](07_registration.md).

## Lessons Learned

### 1. No monolith SKILL.md

SKILL.md is an **index only** — links to sub-skills, MCP tools table, CLI summary. All content in separate focused files. See [03_skill-md-as-index.md](03_skill-md-as-index.md).

### 2. Investigate before documenting

The old `formats.md` listed `.parquet` and `.feather` as supported — but they were **not registered** in `_builtin_handlers.py`. A `_load_parquet` function existed but was never added to `_LOADER_MAP`.

**Always verify against actual source code:**
- Check `_builtin_handlers.py` for registered formats
- Check `__init__.py` for exported functions
- Check `_save.py` / `_load.py` for actual signatures and behavior
- Run small experiments if uncertain

### 3. Cover main features with actual examples

Each sub-skill file must show:
- **Actual function signatures** (from source, not memory)
- **Real code examples** that would run
- **Edge cases** (e.g., `use_caller_path` — when wrappers break path routing)
- **Tables** for structured data (path routing contexts, format support)

Example — `save-and-load.md` covers:
```
save() signature with all 9 parameters
Auto path routing table (Script/Jupyter/Interactive/Absolute)
use_caller_path — why wrappers need it, with before/after
symlink_from_cwd — creates symlink from cwd to saved file
symlink_to — creates symlink at explicit path
no_csv — skip auto CSV export for images
dry_run — preview resolved path
f-string paths — evaluated with caller's variables
load() signature, glob support, caching
Two-tier registry — decorator and direct form
```

### 4. Keep consistent across README, Sphinx, and skills

When you find a discrepancy (e.g., README says "Four Interfaces" but skills say five), fix all three:
- `README.md`
- `docs/sphinx/*.rst`
- `_skills/<pip-name>/*.md`

### 5. Real files in packages, not symlinks

Symlinks break in Python wheels. The package directory `src/<pkg>/_skills/<pip-name>/` must contain real files so they bundle into the wheel. Export copies (`~/.claude/skills/scitex/<pip-name>/`) are refreshed via `scitex-dev skills export`.

## Reference Implementation

**scitex-io** (`~/proj/scitex-io/src/scitex_io/_skills/scitex-io/`) is the reference:
- 9 focused sub-skill files, no monolith
- SKILL.md is index-only with MCP tools table and CLI summary
- Each sub-skill verified against `_builtin_handlers.py` and `_save.py`
- Consistent with README.md and `docs/sphinx/` (Five Interfaces with HTTP optional, format tables)
- Real files (not symlinks) bundled by hatch under `src/<pkg>/_skills/`
