best-practices-skills

# Skills Best Practices Use this skill when creating or reviewing skills under `.pi/skills/`. ## Runtime self-improvement tier Declare in frontmatter when a skill is more than a simple one-shot CLI: ```yaml runtime_self_improvement: none | basic | substantial ``` | Tier | Verify command | Maintainer ticket | Agent post-run section | |------|----------------|-------------------|------------------------| | `none` | No | No | No | | `basic` | `sanity.sh` only | No | Optional | | `substantial` | `./run.sh verify` + receipt | `file-maintainer-ticket` | Required in `agents/<skill>/AGENTS.md` | Full contract: `references/runtime-self-improvement.md` Template files: `references/templates/runtime-self-improvement/` Validator enforces `substantial` via rules `RSI001`–`RSI004` in `scripts/validate_skill.py`. Rollout: wire substantial skills incrementally; `voice-segment-selector` is the reference implementation. ## ArangoDB Access Policy (NON-NEGOTIABLE) - `/memory` is the ONLY skill that accesses ArangoDB directly - `/ops-arango` handles admin ops (backups, indexes, migrations) - `monitor-memory` has read-only exception for health probes (documented) - ALL other skills MUST use `memory/run.sh` subcommands: - `memory recall` — semantic + BM25 search - `memory learn` — store lessons/data - `memory sample` — random document sampling - `memory tag` — post-insert tag stamping - `memory count` — collection statistics - `memory archive-session` — episodic archival - NEVER: `from arango import ArangoClient` - NEVER: `sys.path.insert(0, MEMORY_PATH)` - NEVER: hardcoded passwords or raw `/_api/cursor` calls ## Storage Policy (NON-NEGOTIABLE) **The root NVMe is for CODE ONLY.** All heavy artifacts MUST live on the 12TB drive and be symlinked back. This is enforced by `/skills-broadcast` and `/ops-workstation`. ### What MUST be on `/mnt/storage12tb` | Category | Examples | Storage Path | |----------|----------|--------------| | **Model weights** | `.safetensors`, `.gguf`, `.bin`, `.pt` | `/mnt/storage12tb/skills/<skill-name>/models/` | | **Training logs** | RVC logs, checkpoints, tensorboard | `/mnt/storage12tb/skills/<skill-name>/logs/` | | **Extracted data** | `extracted_runs/`, PDF extractions | `/mnt/storage12tb/skills/<skill-name>/extracted_runs/` | | **Generated outputs** | batch results, GRPO outputs | `/mnt/storage12tb/skills/<skill-name>/outputs/` | | **Datasets** | training data, WAV files, corpora | `/mnt/storage12tb/skills/<skill-name>/data/` | | **Work dirs** | temp processing, intermediate files | `/mnt/storage12tb/skills/<skill-name>/work/` | | **Backups** | `.backups/`, snapshots | `/mnt/storage12tb/backups/<project>/` | ### What MUST NEVER be synced by `/skills-broadcast` These directories are **excluded from rsync** and must not exist as real directories in skill folders (only as symlinks to `/mnt/storage12tb/`): `.venv`, `node_modules`, `__pycache__`, `models`, `rvc`, `outputs`, `logs`, `data`, `pods`, `extracted_runs`, `work`, `weights`, `checkpoints`, `artifacts`, `sessions`, `papers`, `datasets`, `*.safetensors`, `*.gguf`, `*.bin`, `*.pt` ### How to set up a new heavy artifact directory ```bash # 1. Create the storage location on 12TB drive mkdir -p /mnt/storage12tb/skills/<skill-name>/models # 2. Move existing data (if any) mv /path/to/skill/models/* /mnt/storage12tb/skills/<skill-name>/models/ # 3. Remove the directory and create symlink rmdir /path/to/skill/models ln -s /mnt/storage12tb/skills/<skill-name>/models /path/to/skill/models ``` ### Enforcement - `/skills-broadcast sanity` FAILS if any skill has non-symlinked dirs >100MB - `/ops-workstation slim` reports storage policy violations - `.gitignore` in every skill should exclude heavy artifact patterns ## Required structure - A skill is a folder with a required `SKILL.md` at the root. - `SKILL.md` must start with YAML frontmatter (no code fences). - Frontmatter delimiters must be standalone lines: opening `---` on line 1 and closing `---` on its own line. - Frontmatter must include `name` and `description`. - The `description` should contain explicit trigger contexts (what users will say). - Keep `SKILL.md` concise; move large content into `references/` or `scripts/`. - Avoid extra docs (CHANGELOG) inside the skill folder. - README.md is allowed for skills that declare `provides:` (composable primitives with human developer audiences). SKILL.md is for agents; README.md is for humans browsing the directory. ## Composition Frontmatter (Valence Shell) Skills are like chemical elements — they bind to each other through defined interfaces. The `provides:` and `composes:` frontmatter fields declare a skill's **valence shell**: what it offers to others and what it needs from others. ### Required composition fields ```yaml --- name: my-skill description: > What this skill does and trigger phrases. triggers: - natural language phrase users will say - another trigger phrase provides: - capability-a # What this skill outputs/offers - capability-b composes: - memory # Skills this delegates to (by name) - scillm - extractor complies: - best-practices-skills - best-practices-python --- ``` ### Field definitions | Field | Type | Required | Description | |-------|------|----------|-------------| | `triggers` | list[str] | **Yes** | Natural-language phrases users will say. Parsed at runtime by `skill-selector` extension for BM25-style matching. Skills without triggers are invisible to implicit routing. | | `provides` | list[str] | Yes | Capabilities this skill makes available. Used by `/skill-lab` gap detector. | | `composes` | list[str] | Yes | Skills this skill delegates to via subprocess/import. Empty list `[]` if self-contained. Parsed at runtime by `skill-selector` extension for dependency expansion — when a skill is selected, its `composes` deps are automatically included in context. | | `complies` | list[str] | Yes | Best-practices or standards this skill must satisfy. This is audit metadata for `/skills-ci` and skill maintainers, not runtime delegation. Every skill must include `best-practices-skills`; add domain packs such as `best-practices-python`, `best-practices-scillm`, or `best-practices-react` when applicable. | | `taxonomy` | list[str] | Recommended | Federated taxonomy bridge tags for multi-hop discovery via `/memory`. Uses standard vocabulary: `precision`, `resilience`, `fragility`, `corruption`, `loyalty`, `stealth`, plus domain tags. | ### Runtime consumption (skill-selector extension) The `.pi/extensions/skill-selector.ts` extension reads frontmatter at session start: - **`triggers`** → Built into an inverted token index. When users type natural language (no `/skill-name` ref), the extension scores the prompt against triggers+descriptions to select relevant skills. **Skills without triggers are invisible to implicit routing.** - **`composes`** → Parsed into a dependency map. When a skill is selected (explicitly or via trigger match), all its `composes` dependencies are automatically pulled into context. This replaced a hardcoded static map (Feb 2026) — the extension now reads live frontmatter. - **`provides`** → Used by `/skill-lab` for gap detection and capability graph traversal. Not yet consumed by skill-selector (future: reverse-index for "I need X capability" queries). - **`complies`** → Used by `/skills-ci`, `/skill-maintainer`, and review workflows to select applicable best-practices checks for this skill. It does not pull skills into context and must not be used as a substitute for `composes`. ### Binding affinity rules 1. **Skills MUST declare all skills they delegate to** in `composes:`. 2. **Skills MUST declare what they output** in `provides:`. 3. **Skills MUST declare applicable audit standards** in `complies:`. 4. **Self-contained skills** (no external dependencies) use `composes: []`. 5. **Lab skills** (prompt-lab, gpt-lab, classifier-lab) are **catalysts** — they create new skills without being consumed. They `provide: [skill-creation]`. 6. **Composite skills** are molecules — stable combinations of existing skills wired together by a thin orchestrator. ### Capability vocabulary (standardized provides values) | Capability | Skills that provide it | |------------|----------------------| | `llm-completion` | scillm, codex | | `embedding` | embedding | | `memory-recall` | memory | | `memory-learn` | memory | | `web-search` | brave-search, dogpile | | `pdf-extraction` | extractor, review-pdf | | `security-scan` | hack, security-scan | | `skill-creation` | prompt-lab, gpt-lab, classifier-lab | | `skill-validation` | skills-ci, best-practices-skills | | `competitive-selection` | battle | | `hardening` | anvil | | `docker-isolation` | battle, hack | | `human-interview` | interview | | `task-planning` | plan | | `task-orchestration` | orchestrate | | `taxonomy-tagging` | taxonomy | | `progress-tracking` | task-monitor | New capabilities should be added to `references/capability_vocabulary.yml`. ### Graph Registration (Multi-Hop Discovery) Skills SHOULD be registered in `/memory` as nodes in the knowledge graph. This enables multi-hop traversal — when `/skill-lab` needs a capability, it can traverse `composes` edges to find transitive dependencies, just like `/memory` traverses `relates_to` edges for knowledge discovery. ``` skill:extractor ──composes──► skill:memory ──composes──► skill:scillm ──provides──► capability:pdf-extraction skill:learn-datalake ──composes──► skill:extractor ──composes──► skill:review-pdf ──composes──► skill:memory ``` This is analogous to chemical bonding — the graph reveals which elements naturally form molecules. `/taxonomy` tags provide the bridge keywords that enable cross-domain discovery (a security skill and an extraction skill might share `taxonomy:validation` tags). Registration pattern: ```python from common.memory_client import learn, MemoryScope # Register skill as a knowledge node learn( problem=f"What does {skill_name} provide?", solution=f"Provides: {', '.join(provides)}. Composes: {', '.join(composes)}", scope=MemoryScope.OPERATIONAL, tags=["skill_registry", skill_name] + provides, ) ``` ### Machine-parseable rules See `references/rules.yml` for the complete machine-parseable rule set that `/skills-ci` and `/skill-lab` validate against. See `references/composition_manifest.yml` for the schema `/skill-lab` uses when planning new composite skills. Run `./sanity.sh` in this skill to enforce the strict frontmatter gate across all skills. Run `scripts/sync_skill_compliance.py --skills-root skills --check` from the repository root to verify that every skill declares deterministic `complies:` metadata for skill-maintainer and `/skills-ci`. ## Design patterns 1. **Progressive disclosure** - Layer 1: Frontmatter (`name`, `description`) for routing. - Layer 2: `SKILL.md` body for the workflow map. - Layer 3: `scripts/`, `references/`, `assets/` for details on demand. 2. **Guardrails vs freedom** - High-variance tasks: instructions only. - Fragile/repetitive tasks: scripts with parameters. - Mixed tasks: decision tree in `SKILL.md` + references/scripts. 3. **Single source of truth** - Put schemas, long examples, and variants in `references/`. - `SKILL.md` should point to references, not duplicate them. 4. **Project state transparency** - Every complex or multi-service skill SHOULD expose a state-at-a-glance/readiness report. - The report is a hallucination guard: it must say `NOT_TESTED`, `NOT_ESTABLISHED`, `NEEDS_ATTENTION`, or `BLOCKED` when evidence is missing. - Do not summarize skipped routes as success. Skipped required release checks are release blockers; skipped non-required checks are coverage gaps. ## Typed Seam Contracts (Multi-Layer Skills, NON-NEGOTIABLE) Any skill whose workflow crosses a boundary — into another skill, a runtime (Tau), a transport (Surf), a copied worker script, or a subprocess — MUST validate every artifact that crosses that boundary with a typed model at the **producer** side, and the validation MUST be unignorable. Derived from the 2026-07-31/08-01 /ask incident cluster: seven distinct outages (agent-skills #1123, #1124, #1134–#1139) were all the same failure class — layer N emitted something layer N+1 rejects or misreads, nothing checked the seam, and the drift surfaced hours later as an unrelated symptom (silent hour-long polls, wrong browser tab closed, unrecoverable seats). Rules: 1. **One typed model per crossing artifact.** Pydantic models for package code; stdlib `@dataclass` with an explicit `validate()` for scripts that must stay copy-safe/self-contained. Ad hoc dict poking is not validation. 2. **Producer-side, not consumer-side.** The producer runs the check before emitting, so the violation is attributed to the code that drifted, with its context intact. Where feasible, run the **consumer's actual validator** (e.g. /ask runs installed Tau's `validate_dag_contract` on every emitted DAG before any browser opens). 3. **Unignorable: pass, self-heal, or raise.** Exactly three outcomes. A violation first gets a deterministic, narrow repair attempt derived from a known failure class; a successful repair is re-validated and recorded (`SELF_HEALED` + the exact repairs). Anything else raises / exits non-zero so the orchestrator fails the step closed. No advisory warnings — a drifting agent will ignore them. 4. **Stamp the pass.** A validated artifact carries a `seam_validation: {kind, status: PASS}` receipt so downstream readers can