pi-skill-search 0.1.0

package/skills/exa-search/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: exa-search
+description: "Web toolkit powered by Exa, tuned for scientific and technical content. Use this skill when the user needs to search the web or fetch/extract URL content. Covers: web search (semantic lookups, research, current info — with optional research-paper category and academic domain filtering) and URL extraction (fetching pages, articles, academic PDFs in batch). Use this skill for web-related tasks when the user wants high-quality search or scholarly filtering via category=research paper. Triggers on requests to search, look up, fetch a page, or extract an article."
+---
+
+# Exa Web Toolkit
+
+A skill for web-powered research tasks backed by [Exa](https://exa.ai): web search and URL extraction. Exa's index combines high-quality keyword and semantic retrieval, which makes it well-suited to scientific, technical, and conceptual queries.
+
+## Routing — pick the right capability
+
+Read the user's request and match it to one of the capabilities below. Read the corresponding reference file for detailed instructions before running commands.
+
+| User wants to... | Capability | Where |
+|---|---|---|
+| Look something up, research a topic, find current info | **Web Search** | `(see docs)` |
+| Fetch content from a specific URL (webpage, article, PDF) | **Web Extract** | `(see docs)` |
+| Install or authenticate | **Setup** | Below |
+
+### Decision guide
+
+- **Default to Web Search** for topic lookups, research questions, or "what is X?" queries. When the topic is scientific or technical, pass `--category "research paper"` to bias toward scholarly sources, and/or an academic `--include-domains` allowlist. See `(see docs)` for the two-pass academic strategy.
+- **Use Web Extract** when the user provides a URL or asks you to read/fetch a specific page. Prefer this over the built-in WebFetch for batch extraction (multiple URLs in one call) and for academic PDFs.
+
+### Academic source priority
+
+For technical or scientific queries, prefer academic and scientific sources:
+- Peer-reviewed journal articles and conference proceedings over blog posts or news
+- Preprints (arXiv, bioRxiv, medRxiv) when peer-reviewed versions aren't available
+- Institutional and government sources (NIH, WHO, NASA, NIST) over commercial sites
+- Primary research over secondary summaries
+
+Two levers to steer Exa toward scholarly content:
+1. `--category "research paper"` biases retrieval toward scholarly sources.
+2. `--include-domains` with a scholarly allowlist (arxiv.org, nature.com, pubmed.ncbi.nlm.nih.gov, etc.) restricts the domain pool.
+
+Combine both for strictly academic results. See `(see docs)` for the full pattern.
+
+When citing academic sources, include author names and publication year where available (e.g., [Smith et al., 2025](url)) in addition to the standard citation format. If a DOI is present, prefer the DOI link.
+
+---
+
+### Authentication
+
+All commands read the API key from the `EXA_API_KEY` environment variable. Get your Exa API key at [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys).
+
+First, check if a `.env` file exists in the project root and contains `EXA_API_KEY`. If so, load it:
+
+```bash
+dotenv -f .env run -- uv run --with exa-py python "$SKILL_PATH/scripts/exa_search.py" "your query"
+```
+
+If `dotenv` isn't available, install it: `pip install python-dotenv[cli]` or `uv pip install python-dotenv[cli]`.
+
+If there's no `.env`, export the key for the session:
+
+```bash
+
+### Tracking header
+
+Every script in this skill sets the `x-exa-integration` request header to `k-dense-ai--scientific-agent-skills` so Exa can attribute usage from the K-Dense AI scientific-agent-skills repo to this integration. Do not remove or rename this header when adapting the scripts.
+
+---
+
+## Files in this skill
+
+- `SKILL.md` — this file (routing and setup)
+- `(see docs)` — detailed web search reference with academic strategy
+- `(see docs)` — URL content extraction reference
+- `scripts/exa_search.py` — CLI wrapper around `client.search_and_contents`
+- `scripts/exa_extract.py` — CLI wrapper around `client.get_contents`
+```

package/skills/executing-plans/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute all tasks, report when complete.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Tasks
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Stop when blocked, don't guess
+- Never start implementation on main/master branch without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
+

package/skills/exploratory-data-analysis/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: exploratory-data-analysis
+description: Perform comprehensive exploratory data analysis on scientific data files across 200+ file formats. This skill should be used when analyzing any scientific data file to understand its structure, content, quality, and characteristics. Automatically detects file type and generates detailed markdown reports with format-specific analysis, quality metrics, and downstream analysis recommendations. Covers chemistry, bioinformatics, microscopy, spectroscopy, proteomics, metabolomics, and general scientific data formats.
+---
+
+# Exploratory Data Analysis
+
+## Overview
+
+Perform comprehensive exploratory data analysis (EDA) on scientific data files across multiple domains. This skill provides automated file type detection, format-specific analysis, data quality assessment, and generates detailed markdown reports suitable for documentation and downstream analysis planning.
+
+**Key Capabilities:**
+- Automatic detection and analysis of 200+ scientific file formats
+- Comprehensive format-specific metadata extraction
+- Data quality and integrity assessment
+- Statistical summaries and distributions
+- Visualization recommendations
+- Downstream analysis suggestions
+- Markdown report generation
+
+## When to Use This Skill
+
+Use this skill when:
+- User provides a path to a scientific data file for analysis
+- User asks to "explore", "analyze", or "summarize" a data file
+- User wants to understand the structure and content of scientific data
+- User needs a comprehensive report of a dataset before analysis
+- User wants to assess data quality or completeness
+- User asks what type of analysis is appropriate for a file
+
+## Supported File Categories
+
+The skill has comprehensive coverage of scientific file formats organized into six major categories:
+
+## Workflow
+
+### Step 1: File Type Detection
+
+When a user provides a file path, first identify the file type:
+
+1. Extract the file extension
+2. Look up the extension in the appropriate reference file
+3. Identify the file category and format description
+4. Load format-specific information
+
+**Example:**
+```
+User: "Analyze data.fastq"
+→ Extension: .fastq
+→ Category: bioinformatics_genomics
+→ Format: FASTQ Format (sequence data with quality scores)
+→ Reference: (see docs)
+```
+
+### Step 3: Perform Data Analysis
+
+Use the `scripts/eda_analyzer.py` script OR implement custom analysis:
+
+**Option A: Use the analyzer script**
+```python
+# The script automatically:
+# 1. Detects file type
+# 4. Generates markdown report
+
+python scripts/eda_analyzer.py <filepath> [output.md]
+
+**Option B: Custom analysis in the conversation**
+Based on the format information from the reference file, perform appropriate analysis:
+
+For tabular data (CSV, TSV, Excel):
+- Load with pandas
+- Check dimensions, data types
+- Analyze missing values
+- Calculate summary statistics
+- Identify outliers
+- Check for duplicates
+
+### Step 4: Generate Comprehensive Report
+
+Create a markdown report with the following sections:
+
+#### Required Sections:
+1. **Title and Metadata**
+   - Filename and timestamp
+   - File size and location
+
+2. **Basic Information**
+   - File properties
+   - Format identification
+
+3. **File Type Details**
+   - Format description from reference
+
+### Step 5: Save Report
+
+Save the markdown report with a descriptive filename:
+- Pattern: `{original_filename}_eda_report.md`
+- Example: `experiment_data.fastq` → `experiment_data_eda_report.md`
+
+### Reference File Structure
+
+Each format entry includes:
+- **Description:** What the format is
+- **Typical Data:** What it contains
+- **Use Cases:** Common applications
+- **Python Libraries:** How to read it (with code examples)
+- **EDA Approach:** Specific analyses to perform
+
+**Example lookup:**
+```markdown
+### .pdb - Protein Data Bank
+**Description:** Standard format for 3D structures of biological macromolecules
+**Typical Data:** Atomic coordinates, residue information, secondary structure
+**Use Cases:** Protein structure analysis, molecular visualization, docking
+**Python Libraries:**
+- `Biopython`: `Bio.PDB`
+
+

package/skills/external-context/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: external-context
+description: Invoke parallel document-specialist agents for external web searches and documentation lookup
+---
+
+# External Context Skill
+
+Fetch external documentation, references, and context for a query. Decomposes into 2-5 facets and spawns parallel document-specialist Claude agents.
+
+## Usage
+
+```
+external-context <topic or question>
+```
+
+### Examples
+
+```
+external-context What are the best practices for JWT token rotation in Node.js?
+external-context Compare Prisma vs Drizzle ORM for PostgreSQL
+external-context Latest React Server Components patterns and conventions
+```
+
+## Protocol
+
+### Step 1: Facet Decomposition
+
+Given a query, decompose into 2-5 independent search facets:
+
+```markdown
+## Search Decomposition
+
+**Query:** <original query>
+
+### Facet 1: <facet-name>
+- **Search focus:** What to search for
+- **Sources:** Official docs, GitHub, blogs, etc.
+
+### Facet 2: <facet-name>
+...
+```
+
+### Step 2: Parallel Agent Invocation
+
+Fire independent facets in parallel via Task tool:
+
+```
+Task(subagent_type="oh-my-claudecode:document-specialist", model="sonnet", prompt="Search for: <facet 1 description>. Use WebSearch and WebFetch to find official documentation and examples. Cite all sources with URLs.")
+
+Task(subagent_type="oh-my-claudecode:document-specialist", model="sonnet", prompt="Search for: <facet 2 description>. Use WebSearch and WebFetch to find official documentation and examples. Cite all sources with URLs.")
+```
+
+Maximum 5 parallel document-specialist agents.
+
+### Step 3: Synthesis Output Format
+
+Present synthesized results in this format:
+
+```markdown
+## External Context: <query>
+
+### Key Findings
+1. **<finding>** - Source: [title](url)
+2. **<finding>** - Source: [title](url)
+
+### Detailed Results
+
+#### Facet 1: 
+<aggregated findings with citations>
+
+#### Facet 2: 
+<aggregated findings with citations>
+
+### Sources
+- [Source 1](url)
+- [Source 2](url)
+```
+
+## Configuration
+

package/skills/fastapi/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: fastapi
+description: REST API development framework for scientific web services. Use when building HTTP endpoints, serving ML models as APIs, handling file uploads, or creating microservices. Trigger on imports of fastapi, uvicorn, or mentions of API endpoint, REST service, web server, model serving.
+---
+# fastapi
+
+Use this skill for building scientific web APIs and microservices.
+
+## Core patterns
+
+- **App**: `app = FastAPI(title="My API", version="1.0")`.
+- **Route**: `@app.post("/predict")` with type-annotated parameters.
+- **Request model**: `class PredictionRequest(BaseModel):` with Pydantic validation.
+- **File upload**: `UploadFile` parameter for multipart data.
+- **Run**: `uvicorn.run(app, host="0.0.0.0", port=8000)`.
+
+## Rules
+
+- Always define response models with `response_model=PredictionResponse`.
+- Use `HTTPException(status_code=404, detail="Not found")` for error handling.
+- Add CORS middleware when serving frontend: `CORSMiddleware(allow_origins=["*"])`.
+- Use `BackgroundTasks` for long-running operations.
+
+## Anti-patterns
+
+- Don't block the event loop — use `async def` with `await` for I/O.
+- Don't load ML models inside route handlers — load at startup with `@app.on_event("startup")`.
+- Don't return raw dicts — use Pydantic response models for documentation.
+
+

package/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: finishing-a-development-branch
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Detect Environment
+
+**Determine workspace state before presenting options:**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+This determines which menu to show and how cleanup works:
+
+| State | Menu | Cleanup |
+|-------|------|---------|
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |
+
+### Step 3: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main - is that correct?"
+
+### Step 4: Present Options
+
+**Normal repo and named-branch worktree — present exactly these 4 options:**
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+
+### Step 5: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Get main repo root for CWD safety
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+# Merge first — verify success before removing anything
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
+```
+
+Then: Cleanup worktree (Step 6), then delete branch:
+
+```bash
+git branch -d <feature-branch>
+```

package/skills/flowio/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: flowio
+description: Parse FCS (Flow Cytometry Standard) files v2.0-3.1. Extract events as NumPy arrays, read metadata/channels, convert to CSV/DataFrame, for flow cytometry data preprocessing.
+---
+
+# FlowIO: Flow Cytometry Standard File Handler
+
+## Overview
+
+FlowIO is a lightweight Python library for reading and writing Flow Cytometry Standard (FCS) files. Parse FCS metadata, extract event data, and create new FCS files with minimal dependencies. The library supports FCS versions 2.0, 3.0, and 3.1, making it ideal for backend services, data pipelines, and basic cytometry file operations.
+
+## When to Use This Skill
+
+This skill should be used when:
+
+- FCS files requiring parsing or metadata extraction
+- Flow cytometry data needing conversion to NumPy arrays
+- Event data requiring export to FCS format
+- Multi-dataset FCS files needing separation
+- Channel information extraction (scatter, fluorescence, time)
+- Cytometry file validation or inspection
+- Pre-processing workflows before advanced analysis
+
+**Related Tools:** For advanced flow cytometry analysis including compensation, gating, and FlowJo/GatingML support, recommend FlowKit library as a companion to FlowIO.
+
+## Quick Start
+
+### Basic File Reading
+
+```python
+from flowio import FlowData
+
+# Read FCS file
+flow_data = FlowData('experiment.fcs')
+
+# Get event data as NumPy array
+events = flow_data.as_array()  # Shape: (events, channels)
+```
+
+### Creating FCS Files
+
+```python
+import numpy as np
+from flowio import create_fcs
+
+# Prepare data
+data = np.array([[100, 200, 50], [150, 180, 60]])  # 2 events, 3 channels
+channels = ['FSC-A', 'SSC-A', 'FL1-A']
+
+# Create FCS file
+create_fcs('output.fcs', data, channels)
+```
+
+## Core Workflows
+
+### Reading and Parsing FCS Files
+
+The FlowData class provides the primary interface for reading FCS files.
+
+**Standard Reading:**
+
+```python
+from flowio import FlowData
+
+# Basic reading
+flow = FlowData('sample.fcs')
+
+# Access attributes
+version = flow.version              # '3.0', '3.1', etc.
+event_count = flow.event_count      # Number of events
+channel_count = flow.channel_count  # Number of channels
+pnn_labels = flow.pnn_labels        # Short channel names
+pns_labels = flow.pns_labels        # Descriptive stain names
+
+# Get event data
+events = flow.as_array()            # Preprocessed (gain, log scaling applied)
+raw_events = flow.as_array(preprocess=False)  # Raw data
+```
+
+**Memory-Efficient Metadata Reading:**
+
+When only metadata is needed (no event data):
+
+```python
+# Only parse TEXT segment, skip DATA and ANALYSIS
+flow = FlowData('sample.fcs', only_text=True)
+
+# Access metadata
+metadata = flow.text  # Dictionary of TEXT segment keywords
+print(metadata.get('$DATE'))  # Acquisition date
+print(metadata.get('$CYT'))   # Instrument name
+```
+
+**Handling Problematic Files:**
+
+Some FCS files have offset discrepancies or errors:
+
+```python
+# Ignore offset discrepancies between HEADER and TEXT sections
+flow = FlowData('problematic.fcs', ignore_offset_discrepancy=True)
+
+# Use HEADER offsets instead of TEXT offsets
+flow = FlowData('problematic.fcs', use_header_offsets=True)
+
+# Ignore offset errors entirely
+flow = FlowData('problematic.fcs', ignore_offset_error=True)
+```
+
+**Excluding Null Channels:**
+
+```python
+# Exclude specific channels during parsing
+flow = FlowData('sample.fcs', null_channel_list=['Time', 'Null'])
+```

package/skills/fluidsim/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: fluidsim
+description: Framework for computational fluid dynamics simulations using Python. Use when running fluid dynamics simulations including Navier-Stokes equations (2D/3D), shallow water equations, stratified flows, or when analyzing turbulence, vortex dynamics, or geophysical flows. Provides pseudospectral methods with FFT, HPC support, and comprehensive output analysis.
+---
+
+# FluidSim
+
+## Overview
+
+FluidSim is an object-oriented Python framework for high-performance computational fluid dynamics (CFD) simulations. It provides solvers for periodic-domain equations using pseudospectral methods with FFT, delivering performance comparable to Fortran/C++ while maintaining Python's ease of use.
+
+**Key strengths**:
+- Multiple solvers: 2D/3D Navier-Stokes, shallow water, stratified flows
+- High performance: Pythran/Transonic compilation, MPI parallelization
+- Complete workflow: Parameter configuration, simulation execution, output analysis
+- Interactive analysis: Python-based post-processing and visualization
+
+## Core Capabilities
+
+# With FFT support (required for most solvers)
+uv pip install "fluidsim[fft]"
+
+# With MPI for parallel computing
+uv pip install "fluidsim[fft,mpi]"
+```
+
+Set environment variables for output directories (optional):
+
+```bash
+export FLUIDSIM_PATH=/path/to/simulation/outputs
+export FLUIDDYN_PATH_SCRATCH=/path/to/working/directory
+```
+
+No API keys or authentication required.
+
+See `(see docs)` for complete installation instructions and environment configuration.
+
+### 2. Running Simulations
+
+Standard workflow consists of five steps:
+
+**Step 1**: Import solver
+```python
+from fluidsim.solvers.ns2d.solver import Simul
+```
+
+**Step 2**: Create and configure parameters
+```python
+params = Simul.create_default_params()
+params.oper.nx = params.oper.ny = 256
+params.oper.Lx = params.oper.Ly = 2 * 3.14159
+params.nu_2 = 1e-3
+
+### 3. Available Solvers
+
+Choose solver based on physical problem:
+
+**2D Navier-Stokes** (`ns2d`): 2D turbulence, vortex dynamics
+```python
+from fluidsim.solvers.ns2d.solver import Simul
+```
+
+**3D Navier-Stokes** (`ns3d`): 3D turbulence, realistic flows
+```python
+from fluidsim.solvers.ns3d.solver import Simul
+```
+
+**Stratified flows** (`ns2d.strat`, `ns3d.strat`): Oceanic/atmospheric flows
+
+### 4. Parameter Configuration
+
+Parameters are organized hierarchically and accessed via dot notation:
+
+**Domain and resolution**:
+```python
+params.oper.nx = 256  # grid points
+params.oper.Lx = 2 * pi  # domain size
+```
+
+**Physical parameters**:
+```python
+params.nu_2 = 1e-3  # viscosity
+params.nu_4 = 0     # hyperviscosity (optional)
+```
+
+### 5. Output and Analysis
+
+FluidSim produces multiple output types automatically saved during simulation:
+
+**Physical fields**: Velocity, vorticity in HDF5 format
+```python
+sim.output.phys_fields.plot("vorticity")
+sim.output.phys_fields.plot("vx")
+```
+
+**Spatial means**: Time series of volume-averaged quantities
+```python
+sim.output.spatial_means.plot()
+```
+
+### 6. Advanced Features
+
+**Custom forcing**: Maintain turbulence or drive specific dynamics
+```python
+params.forcing.enable = True
+params.forcing.type = "tcrandom"  # time-correlated random forcing
+params.forcing.forcing_rate = 1.0
+```