pi-skill-search 0.1.0

package/skills/dnanexus-integration/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: dnanexus-integration
+description: DNAnexus cloud genomics platform. Build apps/applets, manage data (upload/download), dxpy Python SDK, run workflows, FASTQ/BAM/VCF, for genomics pipeline development and execution.
+---
+
+# DNAnexus Integration
+
+## Overview
+
+DNAnexus is a cloud platform for biomedical data analysis and genomics. Build and deploy apps/applets, manage data objects, run workflows, and use the dxpy Python SDK for genomics pipeline development and execution.
+
+## When to Use This Skill
+
+This skill should be used when:
+- Creating, building, or modifying DNAnexus apps/applets
+- Uploading, downloading, searching, or organizing files and records
+- Running analyses, monitoring jobs, creating workflows
+- Writing scripts using dxpy to interact with the platform
+- Setting up dxapp.json, managing dependencies, using Docker
+- Processing FASTQ, BAM, VCF, or other bioinformatics files
+- Managing projects, permissions, or platform resources
+
+## Core Capabilities
+
+The skill is organized into five main areas, each with detailed reference documentation:
+
+### 1. App Development
+
+**Purpose**: Create executable programs (apps/applets) that run on the DNAnexus platform.
+
+**Key Operations**:
+- Generate app skeleton with `dx-app-wizard`
+- Write Python or Bash apps with proper entry points
+- Handle input/output data objects
+- Deploy with `dx build` or `dx build --app`
+- Test apps on the platform
+
+**Common Use Cases**:
+- Bioinformatics pipelines (alignment, variant calling)
+- Data processing workflows
+- Quality control and filtering
+
+### 2. Data Operations
+
+**Purpose**: Manage files, records, and other data objects on the platform.
+
+**Key Operations**:
+- Upload/download files with `dxpy.upload_local_file()` and `dxpy.download_dxfile()`
+- Create and manage records with metadata
+- Search for data objects by name, properties, or type
+- Clone data between projects
+- Manage project folders and permissions
+
+**Common Use Cases**:
+- Uploading sequencing data (FASTQ files)
+- Organizing analysis results
+- Searching for specific samples or experiments
+
+### 3. Job Execution
+
+**Purpose**: Run analyses, monitor execution, and orchestrate workflows.
+
+**Key Operations**:
+- Launch jobs with `applet.run()` or `app.run()`
+- Monitor job status and logs
+- Create subjobs for parallel processing
+- Build and run multi-step workflows
+- Chain jobs with output references
+
+**Common Use Cases**:
+- Running genomics analyses on sequencing data
+- Parallel processing of multiple samples
+- Multi-step analysis pipelines
+
+### 4. Python SDK (dxpy)
+
+**Purpose**: Programmatic access to DNAnexus platform through Python.
+
+**Key Operations**:
+- Work with data object handlers (DXFile, DXRecord, DXApplet, etc.)
+- Use high-level functions for common tasks
+- Make direct API calls for advanced operations
+- Create links and references between objects
+- Search and discover platform resources
+
+**Common Use Cases**:
+- Automation scripts for data management
+- Custom analysis pipelines
+- Batch processing workflows
+
+### 5. Configuration and Dependencies
+
+**Purpose**: Configure app metadata and manage dependencies.
+
+**Key Operations**:
+- Write dxapp.json with inputs, outputs, and run specs
+- Install system packages (execDepends)
+- Bundle custom tools and resources
+- Use assets for shared dependencies
+- Integrate Docker containers
+- Configure instance types and timeouts
+
+**Common Use Cases**:
+- Defining app input/output specifications
+- Installing bioinformatics tools (samtools, bwa, etc.)
+
+## Quick Start Examples
+
+### Upload and Analyze Data
+
+import dxpy
+
+# Upload input file
+input_file = dxpy.upload_local_file("sample.fastq", project="project-xxxx")
+
+# Run analysis
+
+

package/skills/do/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: do
+description: Execute a phased implementation plan using subagents. Use when asked to execute, run, or carry out a plan — especially one created by make-plan.
+---
+
+# Do Plan
+
+You are an ORCHESTRATOR. Deploy subagents to execute *all* work. Do not do the work yourself except to coordinate, route context, and verify that each subagent completed its assigned checklist.
+
+## Execution Protocol
+
+### Rules
+
+- Each phase uses fresh subagents where noted (or when context is large/unclear)
+- Assign one clear objective per subagent and require evidence (commands run, outputs, files changed)
+- Do not advance to the next step until the assigned subagent reports completion and the orchestrator confirms it matches the plan
+
+### During Each Phase
+
+Deploy an "Implementation" subagent to:
+1. Execute the implementation as specified
+2. COPY patterns from documentation, don't invent
+3. Cite documentation sources in code comments when using unfamiliar APIs
+4. If an API seems missing, STOP and verify — don't assume it exists
+
+### After Each Phase
+
+Deploy subagents for each post-phase responsibility:
+1. **Run verification checklist** — Deploy a "Verification" subagent to prove the phase worked
+2. **Anti-pattern check** — Deploy an "Anti-pattern" subagent to grep for known bad patterns from the plan
+3. **Code quality review** — Deploy a "Code Quality" subagent to review changes
+4. **Commit only if verified** — Deploy a "Commit" subagent *only after* verification passes; otherwise, do not commit
+
+### Between Phases
+
+Deploy a "Branch/Sync" subagent to:
+- Push to working branch after each verified phase
+- Prepare the next phase handoff so the next phase's subagents start fresh but have plan context
+
+## Failure Modes to Prevent
+
+- Don't invent APIs that "should" exist — verify against docs
+- Don't add undocumented parameters — copy exact signatures
+- Don't skip verification — deploy a verification subagent and run the checklist
+- Don't commit before verification passes (or without explicit orchestrator approval)
+
+
+

package/skills/docker-sandbox/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: docker-sandbox
+description: Containerized execution environments and lab automation. Use when running code in Docker containers, managing development environments, CI/CD pipelines, or automating lab instrument control. Trigger on imports of docker, or mentions of container, sandbox, isolated environment, lab automation, instrument control.
+---
+# docker-sandbox
+
+Use this skill for containerized code execution and lab automation.
+
+## Core patterns
+
+- **Run**: `docker.from_env().containers.run('image', command, volumes={'/host': {'bind': '/container', 'mode': 'rw'}})`.
+- **Build**: `docker.from_env().images.build(path='.', tag='my-image')`.
+- **Exec**: `container.exec_run('python script.py')` for running inside a container.
+- **Cleanup**: Always `container.remove()` and `image.remove()` after use.
+
+## Rules
+
+- Always set `mem_limit` and `cpu_count` to prevent resource exhaustion.
+- Mount volumes read-only when writes aren't needed: `mode='ro'`.
+- Use `detach=True` for long-running processes; `detach=False` for scripts.
+- Clean up containers: `docker.from_env().containers.prune()`.
+
+## Anti-patterns
+
+- Don't run containers without resource limits — runaway processes kill the host.
+- Don't mount sensitive directories (`/etc`, `~/.ssh`) into containers.
+- Don't use `latest` tag in production — pin specific image versions.
+
+

package/skills/docx/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: docx
+description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
+---
+
+# DOCX creation, editing, and analysis
+
+## Overview
+
+A .docx file is a ZIP archive containing XML files.
+
+## Quick Reference
+
+| Task | Approach |
+|------|----------|
+| Read/analyze content | `pandoc` or unpack for raw XML |
+| Create new document | Use `docx-js` - see Creating New Documents below |
+| Edit existing document | Unpack → edit XML → repack - see Editing Existing Documents below |
+
+### Converting .doc to .docx
+
+Legacy `.doc` files must be converted before editing:
+
+```bash
+python scripts/office/soffice.py --headless --convert-to docx document.doc
+```
+
+### Reading Content
+
+```bash
+# Text extraction with tracked changes
+pandoc --track-changes=all document.docx -o output.md
+
+# Raw XML access
+python scripts/office/unpack.py document.docx unpacked/
+```
+
+### Converting to Images
+
+```bash
+python scripts/office/soffice.py --headless --convert-to pdf document.docx
+pdftoppm -jpeg -r 150 document.pdf page
+```
+
+### Accepting Tracked Changes
+
+To produce a clean document with all tracked changes accepted (requires LibreOffice):
+
+```bash
+python scripts/accept_changes.py input.docx output.docx
+```
+
+---
+
+## Creating New Documents
+
+Generate .docx files with JavaScript, then validate. Install: `npm install -g docx`
+
+### Validation
+After creating the file, validate it. If validation fails, unpack, fix the XML, and repack.
+```bash
+python scripts/office/validate.py doc.docx
+```
+
+### Page Size
+
+```javascript
+// CRITICAL: docx-js defaults to A4, not US Letter
+// Always set page size explicitly for consistent results
+sections: [{
+  properties: {
+    page: {
+      size: {
+        width: 12240,   // 8.5 inches in DXA
+        height: 15840   // 11 inches in DXA
+      },
+      margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } // 1 inch margins
+    }
+  },
+
+### Styles (Override Built-in Headings)
+
+Use Arial as the default font (universally supported). Keep titles black for readability.
+
+```javascript
+const doc = new Document({
+  styles: {
+    default: { document: { run: { font: "Arial", size: 24 } } }, // 12pt default
+    paragraphStyles: [
+      // IMPORTANT: Use exact IDs to override built-in styles
+      { id: "Heading1", name: "Heading 1", basedOn: "Normal", next: "Normal", quickFormat: true,
+        run: { size: 32, bold: true, font: "Arial" },
+        paragraph: { spacing: { before: 240, after: 240 }, outlineLevel: 0 } }, // outlineLevel required for TOC
+      { id: "Heading2", name: "Heading 2", basedOn: "Normal", next: "Normal", quickFormat: true,
+        run: { size: 28, bold: true, font: "Arial" },
+
+### Lists (NEVER use unicode bullets)
+
+```javascript
+// ❌ WRONG - never manually insert bullet characters
+new Paragraph({ children: [new TextRun("• Item")] })  // BAD
+new Paragraph({ children: [new TextRun("\u2022 Item")] })  // BAD
+
+// ✅ CORRECT - use numbering config with LevelFormat.BULLET
+const doc = new Document({
+  numbering: {
+    config: [
+      { reference: "bullets",
+        levels: [{ level: 0, format: LevelFormat.BULLET, text: "•", alignment: AlignmentType.LEFT,
+          style: { paragraph: { indent: { left: 720, hanging: 360 } } } }] },
+      { reference: "numbers",
+
+### Tables
+
+**CRITICAL: Tables need dual widths** - set both `columnWidths` on the table AND `width` on each cell. Without both, tables render incorrectly on some platforms.
+
+```javascript
+
+

package/skills/esm/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: esm
+description: Comprehensive toolkit for protein language models including ESM3 (generative multimodal protein design across sequence, structure, and function) and ESM C (efficient protein embeddings and representations). Use this skill when working with protein sequences, structures, or function prediction; designing novel proteins; generating protein embeddings; performing inverse folding; or conducting protein engineering tasks. Supports both local model usage and cloud-based Forge API for scalable inference.
+---
+
+# ESM: Evolutionary Scale Modeling
+
+## Overview
+
+ESM provides state-of-the-art protein language models for understanding, generating, and designing proteins. This skill enables working with two model families: ESM3 for generative protein design across sequence, structure, and function, and ESM C for efficient protein representation learning and embeddings.
+
+## Core Capabilities
+
+### 1. Protein Sequence Generation with ESM3
+
+Generate novel protein sequences with desired properties using multimodal generative modeling.
+
+**When to use:**
+- Designing proteins with specific functional properties
+- Completing partial protein sequences
+- Generating variants of existing proteins
+- Creating proteins with desired structural characteristics
+
+**Basic usage:**
+
+```python
+from esm.models.esm3 import ESM3
+from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig
+
+# Load model locally
+model: ESM3InferenceClient = ESM3.from_pretrained("esm3-sm-open-v1").to("cuda")
+
+# Create protein prompt
+protein = ESMProtein(sequence="MPRT___KEND")  # '_' represents masked positions
+
+# Generate completion
+protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8))
+print(protein.sequence)
+```
+
+**For remote/cloud usage via Forge API:**
+
+```python
+from esm.sdk.forge import ESM3ForgeInferenceClient
+from esm.sdk.api import ESMProtein, GenerationConfig
+
+# Connect to Forge
+model = ESM3ForgeInferenceClient(model="esm3-medium-2024-08", url="https://forge.evolutionaryscale.ai", token="<token>")
+
+# Generate
+protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8))
+```
+
+See `(see docs)` for detailed ESM3 model specifications, advanced generation configurations, and multimodal prompting examples.
+
+### 2. Structure Prediction and Inverse Folding
+
+Use ESM3's structure track for structure prediction from sequence or inverse folding (sequence design from structure).
+
+**Structure prediction:**
+
+```python
+from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig
+
+# Predict structure from sequence
+protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP...")
+protein_with_structure = model.generate(
+    protein,
+    GenerationConfig(track="structure", num_steps=protein.sequence.count("_"))
+)
+
+# Access predicted structure
+coordinates = protein_with_structure.coordinates  # 3D coordinates
+pdb_string = protein_with_structure.to_pdb()
+```
+
+**Inverse folding (sequence from structure):**
+
+```python
+# Design sequence for a target structure
+protein_with_structure = ESMProtein.from_pdb("target_structure.pdb")
+protein_with_structure.sequence = None  # Remove sequence
+
+# Generate sequence that folds to this structure
+designed_protein = model.generate(
+    protein_with_structure,
+    GenerationConfig(track="sequence", num_steps=50, temperature=0.7)
+)
+```
+
+### 3. Protein Embeddings with ESM C
+
+Generate high-quality embeddings for downstream tasks like function prediction, classification, or similarity analysis.
+
+**When to use:**
+- Extracting protein representations for machine learning
+- Computing sequence similarities
+- Feature extraction for protein classification
+- Transfer learning for protein-related tasks
+
+**Basic usage:**
+
+```python
+from esm.models.esmc import ESMC
+from esm.sdk.api import ESMProtein
+
+# Load ESM C model
+model = ESMC.from_pretrained("esmc-300m").to("cuda")
+
+# Get embeddings
+protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP...")
+protein_tensor = model.encode(protein)
+
+# Generate embeddings
+embeddings = model.forward(protein_tensor)
+```

package/skills/etetoolkit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: etetoolkit
+description: Phylogenetic tree toolkit (ETE). Tree manipulation (Newick/NHX), evolutionary event detection, orthology/paralogy, NCBI taxonomy, visualization (PDF/SVG), for phylogenomics.
+---
+
+# ETE Toolkit Skill
+
+## Overview
+
+ETE (Environment for Tree Exploration) is a toolkit for phylogenetic and hierarchical tree analysis. Manipulate trees, analyze evolutionary events, visualize results, and integrate with biological databases for phylogenomic research and clustering analysis.
+
+## Core Capabilities
+
+### 1. Tree Manipulation and Analysis
+
+Load, manipulate, and analyze hierarchical tree structures with support for:
+
+- **Tree I/O**: Read and write Newick, NHX, PhyloXML, and NeXML formats
+- **Tree traversal**: Navigate trees using preorder, postorder, or levelorder strategies
+- **Topology modification**: Prune, root, collapse nodes, resolve polytomies
+- **Distance calculations**: Compute branch lengths and topological distances between nodes
+- **Tree comparison**: Calculate Robinson-Foulds distances and identify topological differences
+
+**Common patterns:**
+
+```python
+from ete3 import Tree
+
+# Load tree from file
+tree = Tree("tree.nw", format=1)
+
+# Basic statistics
+print(f"Leaves: {len(tree)}")
+print(f"Total nodes: {len(list(tree.traverse()))}")
+
+# Prune to taxa of interest
+taxa_to_keep = ["species1", "species2", "species3"]
+tree.prune(taxa_to_keep, preserve_branch_length=True)
+
+# Midpoint root
+midpoint = tree.get_midpoint_outgroup()
+tree.set_outgroup(midpoint)
+
+# Save modified tree
+tree.write(outfile="rooted_tree.nw")
+```
+
+Use `scripts/tree_operations.py` for command-line tree manipulation:
+
+```bash
+# Display tree statistics
+python scripts/tree_operations.py stats tree.nw
+
+# Reroot tree
+python scripts/tree_operations.py reroot tree.nw rooted.nw --midpoint
+
+# Prune to specific taxa
+python scripts/tree_operations.py prune tree.nw pruned.nw --keep-taxa "sp1,sp2,sp3"
+
+# Show ASCII visualization
+python scripts/tree_operations.py ascii tree.nw
+```
+
+### 2. Phylogenetic Analysis
+
+Analyze gene trees with evolutionary event detection:
+
+- **Sequence alignment integration**: Link trees to multiple sequence alignments (FASTA, Phylip)
+- **Species naming**: Automatic or custom species extraction from gene names
+- **Evolutionary events**: Detect duplication and speciation events using Species Overlap or tree reconciliation
+- **Orthology detection**: Identify orthologs and paralogs based on evolutionary events
+- **Gene family analysis**: Split trees by duplications, collapse lineage-specific expansions
+
+**Workflow for gene tree analysis:**
+
+```python
+from ete3 import PhyloTree
+
+# Load gene tree with alignment
+tree = PhyloTree("gene_tree.nw", alignment="alignment.fasta")
+
+# Set species naming function
+def get_species(gene_name):
+    return gene_name.split("_")[0]
+
+tree.set_species_naming_function(get_species)
+
+# Detect evolutionary events
+events = tree.get_descendant_evol_events()
+
+# Analyze events
+for node in tree.traverse():
+    if hasattr(node, "evoltype"):
+        if node.evoltype == "D":
+            print(f"Duplication at {node.name}")
+        elif node.evoltype == "S":
+            print(f"Speciation at {node.name}")
+
+# Extract ortholog groups
+ortho_groups = tree.get_speciation_trees()
+for i, ortho_tree in enumerate(ortho_groups):
+    ortho_tree.write(outfile=f"ortholog_group_{i}.nw")
+```

package/skills/event-log-tracing/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: event-log-tracing
+description: Structured event logging system for worker lifecycle, live agents, and crash recovery. Use when debugging worker crashes, tracing agent lifecycle, or investigating stale runs.
+---
+
+
+# event-log-tracing
+
+Every pi-crew run writes a persistent event log at `.crew/state/runs/<runId>/events.jsonl`. Events are the primary evidence for understanding what happened — especially when workers crash, agents get stuck, or runs become orphaned.
+
+## Event Format
+
+Every event is a JSON object on one line:
+
+```json
+{
+  "time": "2026-05-14T10:27:52.000Z",
+  "type": "worker.spawned",
+  "runId": "team_20260514092752_218fe358085d7115",
+  "taskId": "01_explore",
+  "message": "Worker spawned: pid 12345",
+  "data": { "pid": 12345, "role": "explorer" },
+  "metadata": {
+    "seq": 42,
+    "provenance": "team_runner",
+    "fingerprint": "a1b2c3d4e5f6g7h8"
+  }
+}
+```
+
+**Required fields:** `time`, `type`, `runId`
+**Optional fields:** `taskId`, `message`, `data`, `metadata`
+**Metadata auto-populated:** `seq` (line number), `provenance` (who wrote it), `fingerprint` (for terminal events)
+
+---
+
+## Event Taxonomy
+
+### Worker Lifecycle Events (from child-pi.ts via onLifecycleEvent callback)
+
+| Event | When | Data |
+|---|---|---|
+| `worker.spawned` | Child process starts with a PID | `{pid, cwd}` |
+| `worker.spawn_error` | Spawn failed (no PID, binary not found, permission denied) | `{pid?, error}` |
+| `worker.response_timeout` | No stdout for `responseTimeoutMs` (default 5 min) | `{pid, error}` |
+| `worker.final_drain` | Child finished but lingered — SIGTERM sent | `{pid}` |
+| `worker.hard_kill` | Child still alive after `hardKillMs` — SIGKILL sent | `{pid}` |
+| `worker.exit` | Process exited (before close) | `{pid, exitCode}` |
+| `worker.close` | stdio fully closed | `{pid, exitCode}` |
+
+**Tracing worker crashes:**
+- `worker.spawned` followed by `worker.exit` with non-zero code → worker crashed
+- `worker.spawned` followed immediately by `worker.spawn_error` → spawn failed
+- `worker.spawned` followed by `worker.response_timeout` → worker hung
+- `worker.spawned` followed by `worker.final_drain` → worker lingered but completed
+- `worker.spawned` followed by `worker.hard_kill` → worker had to be forcibly killed
+
+**Tracing "worker blinks":**
+- Widget shows agent appears and disappears within 1 frame
+- Root cause: `worker.spawned` + very fast `worker.exit` (crash during spawn)
+- Look for `worker.spawn_error` with error details (API key, model, binary)
+- `executeWorkers=false` (scaffold mode) means no `worker.spawned` at all — agent completes instantly
+
+### Live Agent Events (from live-agent-manager.ts)
+
+| Event | When | Data |
+|---|---|---|
+| `live_agent.registered` | `registerLiveAgent` called | `{agentId, role, agent, workspaceId, runId, taskId}` |
+| `live_agent.terminated` | `terminateLiveAgent` called | `{agentId, status, role, workspaceId, runId, taskId}` |
+
+These track the full lifecycle from spawn to cleanup.
+
+### Run Lifecycle Events (from task-runner.ts, team-runner.ts)
+
+| Event | When | Data |
+|---|---|---|
+| `run.created` | Run manifest created | `{team, workflow}` |
+| `run.running` | Workflow execution begins | — |
+| `run.completed` | All tasks done, no errors | — |
+| `run.failed` | Run failed (fatal error, cancelled) | `{reason?}` |
+| `task.started` | Task worker spawned | `{role, agent, runtime, cwd}` |
+| `task.progress` | Progress event (activity, turns, tokens) | `{eventType, activityState, toolCount, turns, tokens}` |
+| `task.attention` | Attention needed (no yield, completion guard, etc.) | `{reason, activityState}` |
+| `task.completed` | Task finished successfully | — |
+| `task.failed` | Task failed | `{error?}` |