pi-skill-search 0.1.0

package/skills/autoskill/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: autoskill
+description: Observe the user's screen via screenpipe, detect repeated research workflows, match them against existing scientific-agent-skills, and draft new skills (or composition recipes that chain existing ones) for the patterns not yet covered. Use when the user asks to analyze their recent work and propose skills based on what they actually do. Requires the screenpipe daemon (https://github.com/screenpipe/screenpipe) running locally on port 3030 — the skill has no other data source and will refuse to run if screenpipe is unreachable. All detection runs locally; only redacted cluster summaries reach the LLM.
+---
+
+# autoskill
+
+> **Requires a running [screenpipe](https://github.com/screenpipe/screenpipe) daemon.** This skill has no alternate data source — it reads exclusively from the local screenpipe HTTP API (default `http://localhost:3030`). If the daemon isn't running, `run()` raises `ScreenpipeUnreachable` with install instructions.
+
+> **Network access & environment variables.** This skill makes authenticated HTTP requests to (a) the user's local screenpipe daemon on loopback, and (b) the user-configured LLM backend — one of `http://localhost:1234/v1` (LM Studio, default), `https://api.anthropic.com` (opt-in Claude), or a user-supplied BYOK Foundry gateway. The skill reads three environment variables — `SCREENPIPE_TOKEN`, `ANTHROPIC_API_KEY`, `FOUNDRY_API_KEY` — and uses each only to authenticate to the single endpoint its name implies. No other network destinations, no telemetry, no data egress to any third party.
+
+## Overview
+
+Turn the user's own workflow history — captured passively by the local [screenpipe](https://github.com/screenpipe/screenpipe) daemon — into new skills. This skill is on-demand: the user invokes it with a time window, it queries screenpipe's local HTTP API, clusters repeated workflow patterns, compares each pattern against the existing skills in this repo, and produces a staged folder of proposals the user can review, edit, and promote.
+
+## When to Use This Skill
+
+Invoke this skill when the user asks to:
+- "Analyze my last 4 hours / day / week and propose new skills."
+- "Look at what I've been doing and tell me what's not covered yet."
+- "Draft a skill from my recent workflow."
+- "Find composition recipes for workflows I repeat."
+
+Do **not** invoke it for one-off questions about screenpipe itself, for real-time screen queries, or without an explicit user request — the skill analyzes sensitive local content and must stay explicitly user-triggered.
+
+## Privacy Posture
+
+- **Screenpipe handles app/window filtering at capture time.** Install a starter deny-list by copying `(see docs)` into the user's screenpipe config. Sensitive apps (password managers, messaging, banking) are never OCR'd in the first place.
+- **Raw OCR never leaves the machine.** `scripts/fetch_window.py` pulls data over localhost HTTP. `scripts/cluster.py` reduces the timeline to app/duration/title summaries. `scripts/redact.py` strips emails, API keys, bearer tokens, and phone numbers as defense-in-depth before any cluster summary reaches the LLM.
+- **LLM backend defaults to `local`.** The recommended setup is [LM Studio](https://lmstudio.ai/) running `Gemma-4-31B-it` — strong reasoning at a size that fits on most workstation GPUs, and no data ever leaves your machine. Cloud backends (`claude`, `foundry`) are opt-in and documented in `config.yaml` for users who explicitly want them. Detection and embeddings always run locally regardless of backend choice.
+- **Dry-run mode** (`--plan`) prints the exact timeline that will be analyzed before any LLM call.
+- **TLS for localhost** (optional, for corporate policy): see `(see docs)` for the Caddy pattern.
+
+## Prerequisites
+
+### 1. Screenpipe daemon
+
+Either install the official release or build from source. Either way the daemon binds HTTP on `localhost:3030` by default.
+
+**From source** (recommended if you want the CLI daemon without the desktop GUI):
+
+```bash
+git clone --depth 1 https://github.com/mediar-ai/screenpipe.git
+cd screenpipe
+cargo build -p screenpipe-engine --release
+# System deps (macOS): cmake + full Xcode.app (not just Command Line Tools).
+#   # if xcodebuild plug-ins error: sudo xcodebuild -runFirstLaunch
+./target/release/screenpipe doctor   # confirm permissions + ffmpeg
+./target/release/screenpipe record --disable-audio --use-pii-removal
+```
+
+First run will prompt for macOS Screen Recording permission. Grant it and relaunch.
+
+### 2. Screenpipe API token
+
+The local API now requires bearer auth. Retrieve your token and export it:
+
+```bash
+export SCREENPIPE_TOKEN=$(screenpipe auth token)
+```
+
+(Or set `screenpipe.token` directly in `config.yaml` — env var is preferred since it keeps secrets out of version control.)
+
+### 3. Python environment
+
+Via `pipenv` from the repo root:
+
+```bash
+pipenv install httpx pyyaml sentence-transformers
+```
+
+The embedding model (`sentence-transformers/all-MiniLM-L6-v2`, ~80 MB) downloads on first run.
+
+### 4. Local LLM (default path) — LM Studio
+
+- Install [LM Studio](https://lmstudio.ai/).
+- Download `Gemma-4-31B-it` (or another strong reasoning model; adjust `local.model` in `config.yaml`).
+- Load it via the CLI for headless use (no GUI required):
+
+```bash
+lms load gemma-4-31b-it --context-length 131072 --gpu max -y
+lms status   # confirm server running on :1234
+```
+
+### 5. Cloud LLM backends (optional, opt-in)
+
+Only if you explicitly opt out of local:
+- `claude`: set `ANTHROPIC_API_KEY`, flip `backend: claude` in `config.yaml`.
+- `foundry`: set `FOUNDRY_API_KEY`, flip `backend: foundry`, set `foundry.endpoint` to your corporate gateway URL.
+
+## Architecture
+
+```
+screenpipe daemon (user-installed)
+        │  HTTP on localhost:3030
+        ▼
+scripts/fetch_window.py    → normalized timeline events
+scripts/redact.py          → regex scrub (defense-in-depth)
+scripts/cluster.py         → sessions + clusters (local only)
+scripts/match_skills.py    → top-k vs existing 135 skills (local embeddings)
+scripts/synthesize.py      → LLM judge: reuse / compose / novel
+        │
+        ▼
+~/.autoskill/proposed/<timestamp>/        (default; override with --out)
+  ├── report.md
+
+## Workflow
+
+The skill ships a unified CLI at `scripts/autoskill.py` with three subcommands:
+
+```bash
+python scripts/autoskill.py doctor   --config config.yaml --skills-dir ../
+python scripts/autoskill.py run      --start ... --end ... --config config.yaml
+python scripts/autoskill.py promote  --proposed ~/.autoskill/proposed/<ts> --skills-dir ../ --name <skill>
+
+

package/skills/babysit/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: babysit
+description: Watch a pull request or review cycle until it is ready to merge. Use when asked to babysit, monitor, or keep checking PR comments, reviews, and CI until all actionable issues are resolved.
+---
+
+# Babysit PR
+
+Stay with the PR until it is actually clean. Do not stop after one check pass if comments or review threads are still unresolved.
+
+## Workflow
+
+1. Identify the PR number, branch, and base branch.
+2. Confirm the PR is not draft and inspect mergeability, checks, review decision, comments, and review threads.
+3. Watch pending checks until they finish. Poll at a practical interval, usually 30-60 seconds unless the user asks for a different cadence.
+4. Read new comments and unresolved review threads. Treat bot summaries as useful, but verify actionable findings against the code.
+5. Fix real issues in focused commits, run relevant tests/builds, push, and return to step 2.
+6. Resolve stale review threads only after verifying the code or generated artifact now addresses the comment.
+7. Stop only when checks are passing or intentionally skipped, review decision is acceptable, no actionable comments remain, and no unresolved review threads remain.
+
+## GitHub CLI Checks
+
+Use `gh pr view` for the coarse status:
+
+```bash
+gh pr view <number> --json \
+  number,state,isDraft,mergeable,mergeStateStatus,reviewDecision,headRefOid,statusCheckRollup,url
+```
+
+Resolve the repository owner/name before using GraphQL:
+
+```bash
+repo_json=$(gh repo view --json owner,name)
+owner=$(jq -r '.owner.login // .owner.name' <<<"$repo_json")
+repo=$(jq -r '.name' <<<"$repo_json")
+
+## Operating Rules
+
+- Keep the watcher running while long checks are pending.
+- If a generated file is part of the distribution, verify the source and generated artifact agree before resolving comments.
+- If a bot reports an issue against stale code, confirm whether the thread is outdated or addressed in the latest head.
+- Before final reporting, do one fresh sweep of PR status, unresolved threads, recent comments, and local `git status`.
+- Report concrete evidence: latest commit SHA, check names and results, unresolved thread count, tests run, and any dirty local files left untouched.
+```

package/skills/benchling-integration/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: benchling-integration
+description: Benchling R&D platform integration. Access registry (DNA, proteins), inventory, ELN entries, workflows via API, build Benchling Apps, query Data Warehouse, for lab data management automation.
+---
+
+# Benchling Integration
+
+## Overview
+
+Benchling is a cloud platform for life sciences R&D. Access registry entities (DNA, proteins), inventory, electronic lab notebooks, and workflows programmatically via Python SDK and REST API.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Working with Benchling's Python SDK or REST API
+- Managing biological sequences (DNA, RNA, proteins) and registry entities
+- Automating inventory operations (samples, containers, locations, transfers)
+- Creating or querying electronic lab notebook entries
+- Building workflow automations or Benchling Apps
+- Syncing data between Benchling and external systems
+- Querying the Benchling Data Warehouse for analytics
+- Setting up event-driven integrations with AWS EventBridge
+
+## Core Capabilities
+
+### 1. Authentication & Setup
+
+**Python SDK Installation:**
+```python
+# Stable release
+uv pip install benchling-sdk
+# or with Poetry
+poetry add benchling-sdk
+```
+
+**Authentication Methods:**
+
+API Key Authentication (recommended for scripts):
+```python
+from benchling_sdk.benchling import Benchling
+from benchling_sdk.auth.api_key_auth import ApiKeyAuth
+
+benchling = Benchling(
+    url="https://your-tenant.benchling.com",
+    auth_method=ApiKeyAuth("your_api_key")
+)
+
+### 2. Registry & Entity Management
+
+Registry entities include DNA sequences, RNA sequences, AA sequences, custom entities, and mixtures. The SDK provides typed classes for creating and managing these entities.
+
+**Creating DNA Sequences:**
+```python
+from benchling_sdk.models import DnaSequenceCreate
+
+sequence = benchling.dna_sequences.create(
+    DnaSequenceCreate(
+        name="My Plasmid",
+        bases="ATCGATCG",
+        is_circular=True,
+        folder_id="fld_abc123",
+        schema_id="ts_abc123",  # optional
+
+# List all DNA sequences (returns a generator)
+sequences = benchling.dna_sequences.list()
+for page in sequences:
+    for seq in page:
+        print(f"{seq.name} ({seq.id})")
+
+# Check total count
+total = sequences.estimated_count()
+```
+
+**Key Operations:**
+- Create: `benchling.<entity_type>.create()`
+- Read: `benchling.<entity_type>.get(id)` or `.list()`
+- Update: `benchling.<entity_type>.update(id, update_object)`
+- Archive: `benchling.<entity_type>.archive(id)`
+
+Entity types: `dna_sequences`, `rna_sequences`, `aa_sequences`, `custom_entities`, `mixtures`
+
+For comprehensive SDK reference and advanced patterns, refer to `(see docs)`.
+
+### 3. Inventory Management
+
+Manage physical samples, containers, boxes, and locations within the Benchling inventory system.
+
+**Creating Containers:**
+```python
+from benchling_sdk.models import ContainerCreate
+
+container = benchling.containers.create(
+    ContainerCreate(
+        name="Sample Tube 001",
+        schema_id="cont_schema_abc123",
+        parent_storage_id="box_abc123",  # optional
+        fields=benchling.models.fields({"concentration": "100 ng/μL"})
+    )
+
+# Transfer a container to a new location
+transfer = benchling.containers.transfer(
+    container_id="cont_abc123",
+    destination_id="box_xyz789"
+)
+
+

package/skills/bgpt-paper-search/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: bgpt-paper-search
+description: Search scientific papers and retrieve structured experimental data extracted from full-text studies via the BGPT MCP server. Returns 25+ fields per paper including methods, results, sample sizes, quality scores, and conclusions. Use for literature reviews, evidence synthesis, and finding experimental details not available in abstracts alone.
+---
+
+# BGPT Paper Search
+
+## Overview
+
+BGPT is a remote MCP server that searches a curated database of scientific papers built from raw experimental data extracted from full-text studies. Unlike traditional literature databases that return titles and abstracts, BGPT returns structured data from the actual paper content — methods, quantitative results, sample sizes, quality assessments, and 25+ metadata fields per paper.
+
+## When to Use This Skill
+
+Use this skill when:
+- Searching for scientific papers with specific experimental details
+- Conducting systematic or scoping literature reviews
+- Finding quantitative results, sample sizes, or effect sizes across studies
+- Comparing methodologies used in different studies
+- Looking for papers with quality scores or evidence grading
+- Needing structured data from full-text papers (not just abstracts)
+- Building evidence tables for meta-analyses or clinical guidelines
+
+### Claude Desktop / Claude Code
+
+Add to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "bgpt": {
+      "command": "npx",
+      "args": ["mcp-remote", "https://bgpt.pro/mcp/sse"]
+    }
+  }
+}
+```
+
+### npm (alternative)
+
+```bash
+npx bgpt-mcp
+```
+
+## Usage
+
+Once configured, use the `search_papers` tool provided by the BGPT MCP server:
+
+```
+Search for papers about: "CRISPR gene editing efficiency in human cells"
+```
+
+The server returns structured results including:
+- **Title, authors, journal, year, DOI**
+- **Methods**: Experimental techniques, models, protocols
+- **Results**: Key findings with quantitative data
+- **Sample sizes**: Number of subjects/samples
+- **Quality scores**: Study quality assessments
+- **Conclusions**: Author conclusions and implications
+
+## Pricing
+
+- **Free tier**: 50 searches per network, no API key required
+- **Paid**: $0.01 per result with an API key from [bgpt.pro/mcp](https://bgpt.pro/mcp)
+
+
+
+

package/skills/biopython/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: biopython
+description: Computational biology and bioinformatics toolkit. Use when working with DNA/RNA/protein sequences, BLAST searches, PDB structures, phylogenetic trees, or GenBank records. Trigger on imports of Bio, Bio.Seq, Bio.Blast, Bio.PDB, or mentions of sequence alignment, genome, protein structure, phylogeny.
+---
+# biopython
+
+Use this skill for computational biology and bioinformatics.
+
+## Core patterns
+
+- **Sequences**: `Seq('ATCG')` → `.complement()`, `.translate()`, `.reverse_complement()`.
+- **BLAST**: `NCBIWWW.qblast('blastn', 'nt', sequence)` for remote BLAST.
+- **PDB**: `PDBParser().get_structure('1a8o', '1a8o.pdb')` for 3D structure analysis.
+- **Phylogeny**: `Phylo.read('tree.nwk', 'newick')` for tree visualization.
+- **GenBank**: `SeqIO.parse('genome.gb', 'genbank')` for annotation parsing.
+
+## Rules
+
+- Always use `SeqIO` for file I/O — don't parse FASTA/GenBank manually.
+- Handle ambiguous bases (`N`, `R`, `Y`) explicitly in sequence operations.
+- For BLAST, respect NCBI rate limits — add delays between queries.
+
+## Anti-patterns
+
+- Don't compare sequences as strings — use `seq1 == seq2` which handles case.
+- Don't parse XML BLAST results manually — use `NCBIXML.parse()`.
+- Don't store full genome sequences in memory — iterate with `SeqIO.parse()`.
+
+

package/skills/bioservices/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: bioservices
+description: Unified Python interface to 40+ bioinformatics services. Use when querying multiple databases (UniProt, KEGG, ChEMBL, Reactome) in a single workflow with consistent API. Best for cross-database analysis, ID mapping across services. For quick single-database lookups use gget; for sequence/file manipulation use biopython.
+---
+
+# BioServices
+
+## Overview
+
+BioServices is a Python package providing programmatic access to approximately 40 bioinformatics web services and databases. Retrieve biological data, perform cross-database queries, map identifiers, analyze sequences, and integrate multiple biological resources in Python workflows. The package handles both REST and SOAP/WSDL protocols transparently.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Retrieving protein sequences, annotations, or structures from UniProt, PDB, Pfam
+- Analyzing metabolic pathways and gene functions via KEGG or Reactome
+- Searching compound databases (ChEBI, ChEMBL, PubChem) for chemical information
+- Converting identifiers between different biological databases (KEGG↔UniProt, compound IDs)
+- Running sequence similarity searches (BLAST, MUSCLE alignment)
+- Querying gene ontology terms (QuickGO, GO annotations)
+- Accessing protein-protein interaction data (PSICQUIC, IntactComplex)
+- Mining genomic data (BioMart, ArrayExpress, ENA)
+- Integrating data from multiple bioinformatics resources in a single workflow
+
+## Core Capabilities
+
+### 1. Protein Analysis
+
+Retrieve protein information, sequences, and functional annotations:
+
+```python
+from bioservices import UniProt
+
+u = UniProt(verbose=False)
+
+# Search for protein by name
+results = u.search("ZAP70_HUMAN", frmt="tab", columns="id,genes,organism")
+
+# Retrieve FASTA sequence
+sequence = u.retrieve("P43403", "fasta")
+
+# Map identifiers between databases
+kegg_ids = u.mapping(fr="UniProtKB_AC-ID", to="KEGG", query="P43403")
+```
+
+**Key methods:**
+- `search()`: Query UniProt with flexible search terms
+- `retrieve()`: Get protein entries in various formats (FASTA, XML, tab)
+- `mapping()`: Convert identifiers between databases
+
+Reference: `(see docs)` for complete UniProt API details.
+
+### 2. Pathway Discovery and Analysis
+
+Access KEGG pathway information for genes and organisms:
+
+```python
+from bioservices import KEGG
+
+k = KEGG()
+k.organism = "hsa"  # Set to human
+
+# Search for organisms
+k.lookfor_organism("droso")  # Find Drosophila species
+
+# Find pathways by name
+k.lookfor_pathway("B cell")  # Returns matching pathway IDs
+
+# Get pathways containing specific genes
+pathways = k.get_pathway_by_gene("7535", "hsa")  # ZAP70 gene
+
+# Retrieve and parse pathway data
+data = k.get("hsa04660")
+parsed = k.parse(data)
+
+# Extract pathway interactions
+interactions = k.parse_kgml_pathway("hsa04660")
+relations = interactions['relations']  # Protein-protein interactions
+
+### 3. Compound Database Searches
+
+Search and cross-reference compounds across multiple databases:
+
+```python
+from bioservices import KEGG, UniChem
+
+k = KEGG()
+
+# Search compounds by name
+results = k.find("compound", "Geldanamycin")  # Returns cpd:C11222
+
+# Cross-reference KEGG → ChEMBL using UniChem
+u = UniChem()
+chembl_id = u.get_compound_id_from_kegg("C11222")  # Returns CHEMBL278315
+
+

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+---
+
+# Brainstorming Ideas Into Designs
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+
+
+
+## Anti-Pattern: "This Is Too Simple To Need A Design"
+
+Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+
+## Checklist
+
+You MUST create a task for each of these items and complete them in order:
+
+1. **Explore project context** — check files, docs, recent commits
+2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
+3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
+4. **Propose 2-3 approaches** — with trade-offs and your recommendation
+5. **Present design** — in sections scaled to their complexity, get user approval after each section
+6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit
+7. **Spec self-review** — quick inline check for placeholders, contradictions, ambiguity, scope (see below)
+8. **User reviews written spec** — ask user to review the spec file before proceeding
+9. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+
+## Process Flow
+
+```dot
+digraph brainstorming {
+    "Explore project context" [shape=box];
+    "Visual questions ahead?" [shape=diamond];
+    "Offer Visual Companion\n(own message, no other content)" [shape=box];
+    "Ask clarifying questions" [shape=box];
+    "Propose 2-3 approaches" [shape=box];
+    "Present design sections" [shape=box];
+    "User approves design?" [shape=diamond];
+    "Write design doc" [shape=box];
+    "Spec self-review\n(fix inline)" [shape=box];
+    "User reviews spec?" [shape=diamond];
+    "Invoke writing-plans skill" [shape=doublecircle];
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits)
+- Before asking detailed questions, assess scope: if the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately. Don't spend questions refining details of a project that needs to be decomposed first.
+- If the project is too large for a single spec, help the user decompose into sub-projects: what are the independent pieces, how do they relate, what order should they be built? Then brainstorm the first sub-project through the normal design flow. Each sub-project gets its own spec → plan → implementation cycle.
+- For appropriately-scoped projects, ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+
+## After the Design
+
+**Documentation:**
+
+- Write the validated design (spec) to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`
+  - (User preferences for spec location override this default)
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Spec Self-Review:**
+After writing the spec document, look at it with fresh eyes:
+
+1. **Placeholder scan:** Any "TBD", "TODO", incomplete sections, or vague requirements? Fix them.
+2. **Internal consistency:** Do any sections contradict each other? Does the architecture match the feature descriptions?
+3. **Scope check:** Is this focused enough for a single implementation plan, or does it need decomposition?
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design, get approval before moving on
+- **Be flexible** - Go back and clarify when something doesn't make sense
+
+## Visual Companion
+
+A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
+
+**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
+> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
+
+**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
+
+**Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
+
+- **Use the browser** for content that IS visual — mockups, wireframes, layout comparisons, architecture diagrams, side-by-side visual designs
+- **Use the terminal** for content that is text — requirements questions, conceptual choices, tradeoff lists, A/B/C/D text options, scope decisions
+
+A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
+```

package/skills/cancel/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: cancel
+description: Cancel any active OMC mode (autopilot, ralph, ultrawork, ultraqa, swarm, ultrapilot, pipeline, team)
+---
+
+# Cancel Skill
+
+Intelligent cancellation that detects and cancels the active OMC mode.
+
+**The cancel skill is the standard way to complete and exit any OMC mode.**
+When the stop hook detects work is complete, it instructs the LLM to invoke
+this skill for proper state cleanup. If cancel fails or is interrupted,
+retry with `--force` flag, or wait for the 2-hour staleness timeout as
+a last resort.
+
+## What It Does
+
+Automatically detects which mode is active and cancels it:
+- **Autopilot**: Stops workflow, preserves progress for resume
+- **Ralph**: Stops persistence loop, clears linked ultrawork if applicable
+- **Ultrawork**: Stops parallel execution (standalone or linked)
+- **UltraQA**: Stops QA cycling workflow
+- **Swarm**: Stops coordinated agent swarm, releases claimed tasks
+- **Ultrapilot**: Stops parallel autopilot workers
+- **Pipeline**: Stops sequential agent pipeline
+- **Team**: Sends shutdown_request to all teammates, waits for responses, calls TeamDelete, clears linked ralph if present
+- **Team+Ralph (linked)**: Cancels team first (graceful shutdown), then clears ralph state. Cancelling ralph when linked also cancels team first.
+
+## Usage
+
+```
+cancel
+```
+
+Or say: "cancelomc", "stopomc"
+
+## Critical: Deferred Tool Handling
+
+The state management tools (`state_clear`, `state_read`, `state_write`, `state_list_active`,
+`state_get_status`) may be registered as **deferred tools** by Claude Code. Before calling
+any state tool, you MUST first load all of them via `ToolSearch`:
+
+```
+ToolSearch(query="select:mcp__plugin_oh-my-claudecode_t__state_clear,mcp__plugin_oh-my-claudecode_t__state_read,mcp__plugin_oh-my-claudecode_t__state_write,mcp__plugin_oh-my-claudecode_t__state_list_active,mcp__plugin_oh-my-claudecode_t__state_get_status")
+```
+
+If `state_clear` is unavailable or fails, use this **bash fallback** as an **emergency
+escape from the stop hook loop**. This is NOT a full replacement for the cancel flow —
+it only removes state files to unblock the session. Linked modes (e.g. ralph→ultrawork,
+autopilot→ralph/ultraqa) must be cleared separately by running the fallback once per mode.
+
+Replace `MODE` with the specific mode (e.g. `ralplan`, `ralph`, `ultrawork`, `ultraqa`).
+
+**WARNING:** Do NOT use this fallback for `autopilot` or `omc-teams`. Autopilot requires
+`state_write(active=false)` to preserve resume data. omc-teams requires tmux session
+cleanup that cannot be done via file deletion alone.
+
+```bash
+# Fallback: direct file removal when state_clear MCP tool is unavailable
+SESSION_ID="${CLAUDE_SESSION_ID:-${CLAUDECODE_SESSION_ID:-}}"
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || { d="$PWD"; while [ "$d" != "/" ] && [ ! -d "$d/.omc" ]; do d="$(dirname "$d")"; done; echo "$d"; })"
+
+# Cross-platform SHA-256 (macOS: shasum, Linux: sha256sum)
+sha256portable() { printf '%s' "$1" | (sha256sum 2>/dev/null || shasum -a 256) | cut -c1-16; }
+
+# Resolve state directory (supports OMC_STATE_DIR centralized storage)
+if [ -n "${OMC_STATE_DIR:-}" ]; then
+  # Mirror getProjectIdentifier() from worktree-paths.ts
+  SOURCE="$(git remote get-url origin 2>/dev/null || echo "$REPO_ROOT")"
+  HASH="$(sha256portable "$SOURCE")"
+  DIR_NAME="$(basename "$REPO_ROOT" | sed 's/[^a-zA-Z0-9_-]/_/g')"
+  OMC_STATE="$OMC_STATE_DIR/${DIR_NAME}-${HASH}/state"
+  [ ! -d "$OMC_STATE" ] && { echo "ERROR: State dir not found at $OMC_STATE" >&2; exit 1; }
+elif [ "$REPO_ROOT" != "/" ] && [ -d "$REPO_ROOT/.omc" ]; then
+  OMC_STATE="$REPO_ROOT/.omc/state"
+else
+  echo "ERROR: Could not locate .omc state directory" >&2
+  exit 1
+fi
+MODE="ralplan"  # <-- replace with the target mode
+
+# Clear session-scoped state for the specific mode
+if [ -n "$SESSION_ID" ] && [ -d "$OMC_STATE/sessions/$SESSION_ID" ]; then
+  rm -f "$OMC_STATE/sessions/$SESSION_ID/${MODE}-state.json"
+```