@bgicli/bgicli 2.2.8 → 2.2.9

package/data/skills/ctx-tool-design/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: tool-design
+description: This skill should be used when the user asks to "design agent tools", "create tool descriptions", "reduce tool complexity", "implement MCP tools", or mentions tool consolidation, architectural reduction, tool naming conventions, or agent-tool interfaces.
+---
+
+# Tool Design for Agents
+
+Design every tool as a contract between a deterministic system and a non-deterministic agent. Unlike human-facing APIs, agent-facing tools must make the contract unambiguous through the description alone -- agents infer intent from descriptions and generate calls that must match expected formats. Every ambiguity becomes a potential failure mode that no amount of prompt engineering can fix.
+
+## When to Activate
+
+Activate this skill when:
+- Creating new tools for agent systems
+- Debugging tool-related failures or misuse
+- Optimizing existing tool sets for better agent performance
+- Designing tool APIs from scratch
+- Evaluating third-party tools for agent integration
+- Standardizing tool conventions across a codebase
+
+## Core Concepts
+
+Design tools around the consolidation principle: if a human engineer cannot definitively say which tool should be used in a given situation, an agent cannot be expected to do better. Reduce the tool set until each tool has one unambiguous purpose, because agents select tools by comparing descriptions and any overlap introduces selection errors.
+
+Treat every tool description as prompt engineering that shapes agent behavior. The description is not documentation for humans -- it is injected into the agent's context and directly steers reasoning. Write descriptions that answer what the tool does, when to use it, and what it returns, because these three questions are exactly what agents evaluate during tool selection.
+
+## Detailed Topics
+
+### The Tool-Agent Interface
+
+**Tools as Contracts**
+Design each tool as a self-contained contract. When humans call APIs, they read docs, understand conventions, and make appropriate requests. Agents must infer the entire contract from a single description block. Make the contract unambiguous by including format examples, expected patterns, and explicit constraints. Omit nothing that a caller needs to know, because agents cannot ask clarifying questions before making a call.
+
+**Tool Description as Prompt**
+Write tool descriptions knowing they load directly into agent context and collectively steer behavior. A vague description like "Search the database" with cryptic parameter names forces the agent to guess -- and guessing produces incorrect calls. Instead, include usage context, parameter format examples, and sensible defaults. Every word in the description either helps or hurts tool selection accuracy.
+
+**Namespacing and Organization**
+Namespace tools under common prefixes as the collection grows, because agents benefit from hierarchical grouping. When an agent needs database operations, it routes to the `db_*` namespace; when it needs web interactions, it routes to `web_*`. Without namespacing, agents must evaluate every tool in a flat list, which degrades selection accuracy as the count grows.
+
+### The Consolidation Principle
+
+**Single Comprehensive Tools**
+Build single comprehensive tools instead of multiple narrow tools that overlap. Rather than implementing `list_users`, `list_events`, and `create_event` separately, implement `schedule_event` that finds availability and schedules in one call. The comprehensive tool handles the full workflow internally, removing the agent's burden of chaining calls in the correct order.
+
+**Why Consolidation Works**
+Apply consolidation because agents have limited context and attention. Each tool in the collection competes for attention during tool selection, each description consumes context budget tokens, and overlapping functionality creates ambiguity. Consolidation eliminates redundant descriptions, removes selection ambiguity, and shrinks the effective tool set. Vercel demonstrated this principle by reducing their agent from 17 specialized tools to 2 general-purpose tools and achieving better performance -- fewer tools meant less confusion and more reliable tool selection.
+
+**When Not to Consolidate**
+Keep tools separate when they have fundamentally different behaviors, serve different contexts, or must be callable independently. Over-consolidation creates a different problem: a single tool with too many parameters and modes becomes hard for agents to parameterize correctly.
+
+### Architectural Reduction
+
+Push the consolidation principle to its logical extreme by removing most specialized tools in favor of primitive, general-purpose capabilities. Production evidence shows this approach can outperform sophisticated multi-tool architectures.
+
+**The File System Agent Pattern**
+Provide direct file system access through a single command execution tool instead of building custom tools for data exploration, schema lookup, and query validation. The agent uses standard Unix utilities (grep, cat, find, ls) to explore and operate on the system. This works because file systems are a proven abstraction that models understand deeply, standard tools have predictable behavior, agents can chain primitives flexibly rather than being constrained to predefined workflows, and good documentation in files replaces summarization tools.
+
+**When Reduction Outperforms Complexity**
+Choose reduction when the data layer is well-documented and consistently structured, the model has sufficient reasoning capability, specialized tools were constraining rather than enabling the model, or more time is spent maintaining scaffolding than improving outcomes. Avoid reduction when underlying data is messy or poorly documented, the domain requires specialized knowledge the model lacks, safety constraints must limit agent actions, or operations genuinely benefit from structured workflows.
+
+**Build for Future Models**
+Design minimal architectures that benefit from model improvements rather than sophisticated architectures that lock in current limitations. Ask whether each tool enables new capabilities or constrains reasoning the model could handle on its own -- tools built as "guardrails" often become liabilities as models improve.
+
+See [Architectural Reduction Case Study](./references/architectural_reduction.md) for production evidence.
+
+### Tool Description Engineering
+
+**Description Structure**
+Structure every tool description to answer four questions:
+
+1. What does the tool do? State exactly what the tool accomplishes -- avoid vague language like "helps with" or "can be used for."
+2. When should it be used? Specify direct triggers ("User asks about pricing") and indirect signals ("Need current market rates").
+3. What inputs does it accept? Describe each parameter with types, constraints, defaults, and format examples.
+4. What does it return? Document the output format, structure, successful response examples, and error conditions.
+
+**Default Parameter Selection**
+Set defaults to reflect common use cases. Defaults reduce agent burden by eliminating unnecessary parameter specification and prevent errors from omitted parameters. Choose defaults that produce useful results without requiring the agent to understand every option.
+
+### Response Format Optimization
+
+Offer response format options (concise vs. detailed) because tool response size significantly impacts context usage. Concise format returns essential fields only, suitable for confirmations. Detailed format returns complete objects, suitable when full context drives decisions. Document when to use each format in the tool description so agents learn to select appropriately.
+
+### Error Message Design
+
+Design error messages for two audiences: developers debugging issues and agents recovering from failures. For agents, every error message must be actionable -- it must state what went wrong and how to correct it. Include retry guidance for retryable errors, corrected format examples for input errors, and specific missing fields for incomplete requests. An error that says only "failed" provides zero recovery signal.
+
+### Tool Definition Schema
+
+Establish a consistent schema across all tools. Use verb-noun pattern for tool names (`get_customer`, `create_order`), consistent parameter names across tools (always `customer_id`, never sometimes `id` and sometimes `identifier`), and consistent return field names. Consistency reduces the cognitive load on agents and improves cross-tool generalization.
+
+### Tool Collection Design
+
+Limit tool collections to 10-20 tools for most applications, because research shows description overlap causes model confusion and more tools do not always lead to better outcomes. When more tools are genuinely needed, use namespacing to create logical groupings. Implement selection mechanisms: tool grouping by domain, example-based selection hints, and umbrella tools that route to specialized sub-tools.
+
+### MCP Tool Naming Requirements
+
+Always use fully qualified tool names with MCP (Model Context Protocol) to avoid "tool not found" errors.
+
+Format: `ServerName:tool_name`
+
+```python
+# Correct: Fully qualified names
+"Use the BigQuery:bigquery_schema tool to retrieve table schemas."
+"Use the GitHub:create_issue tool to create issues."
+
+# Incorrect: Unqualified names
+"Use the bigquery_schema tool..."  # May fail with multiple servers
+```
+
+Without the server prefix, agents may fail to locate tools when multiple MCP servers are available. Establish naming conventions that include server context in all tool references.
+
+### Using Agents to Optimize Tools
+
+Feed observed tool failures back to an agent to diagnose issues and improve descriptions. Production testing shows this approach achieves 40% reduction in task completion time by helping future agents avoid mistakes.
+
+**The Tool-Testing Agent Pattern**:
+
+```python
+def optimize_tool_description(tool_spec, failure_examples):
+    """
+    Use an agent to analyze tool failures and improve descriptions.
+
+    Process:
+    1. Agent attempts to use tool across diverse tasks
+    2. Collect failure modes and friction points
+    3. Agent analyzes failures and proposes improvements
+    4. Test improved descriptions against same tasks
+    """
+    prompt = f"""
+    Analyze this tool specification and the observed failures.
+
+    Tool: {tool_spec}
+
+    Failures observed:
+    {failure_examples}
+
+    Identify:
+    1. Why agents are failing with this tool
+    2. What information is missing from the description
+    3. What ambiguities cause incorrect usage
+
+    Propose an improved tool description that addresses these issues.
+    """
+
+    return get_agent_response(prompt)
+```
+
+This creates a feedback loop: agents using tools generate failure data, which agents then use to improve tool descriptions, which reduces future failures.
+
+### Testing Tool Design
+
+Evaluate tool designs against five criteria: unambiguity, completeness, recoverability, efficiency, and consistency. Test by presenting representative agent requests and evaluating the resulting tool calls against expected behavior.
+
+## Practical Guidance
+
+### Tool Selection Framework
+
+When designing tool collections:
+1. Identify distinct workflows agents must accomplish
+2. Group related actions into comprehensive tools
+3. Ensure each tool has a clear, unambiguous purpose
+4. Document error cases and recovery paths
+5. Test with actual agent interactions
+
+## Examples
+
+**Example 1: Well-Designed Tool**
+```python
+def get_customer(customer_id: str, format: str = "concise"):
+    """
+    Retrieve customer information by ID.
+
+    Use when:
+    - User asks about specific customer details
+    - Need customer context for decision-making
+    - Verifying customer identity
+
+    Args:
+        customer_id: Format "CUST-######" (e.g., "CUST-000001")
+        format: "concise" for key fields, "detailed" for complete record
+
+    Returns:
+        Customer object with requested fields
+
+    Errors:
+        NOT_FOUND: Customer ID not found
+        INVALID_FORMAT: ID must match CUST-###### pattern
+    """
+```
+
+**Example 2: Poor Tool Design**
+
+This example demonstrates several tool design anti-patterns:
+
+```python
+def search(query):
+    """Search the database."""
+    pass
+```
+
+**Problems with this design:**
+
+1. **Vague name**: "search" is ambiguous - search what, for what purpose?
+2. **Missing parameters**: What database? What format should query take?
+3. **No return description**: What does this function return? A list? A string? Error handling?
+4. **No usage context**: When should an agent use this versus other tools?
+5. **No error handling**: What happens if the database is unavailable?
+
+**Failure modes:**
+- Agents may call this tool when they should use a more specific tool
+- Agents cannot determine correct query format
+- Agents cannot interpret results
+- Agents cannot recover from failures
+
+## Guidelines
+
+1. Write descriptions that answer what, when, and what returns
+2. Use consolidation to reduce ambiguity
+3. Implement response format options for token efficiency
+4. Design error messages for agent recovery
+5. Establish and follow consistent naming conventions
+6. Limit tool count and use namespacing for organization
+7. Test tool designs with actual agent interactions
+8. Iterate based on observed failure modes
+9. Question whether each tool enables or constrains the model
+10. Prefer primitive, general-purpose tools over specialized wrappers
+11. Invest in documentation quality over tooling sophistication
+12. Build minimal architectures that benefit from model improvements
+
+## Gotchas
+
+1. **Vague descriptions**: Descriptions like "Search the database for customer information" leave too many questions unanswered. State the exact database, query format, and return shape.
+2. **Cryptic parameter names**: Parameters named `x`, `val`, or `param1` force agents to guess meaning. Use descriptive names that convey purpose without reading further documentation.
+3. **Missing error recovery guidance**: Tools that fail with generic messages like "Error occurred" provide no recovery signal. Every error response must tell the agent what went wrong and what to try next.
+4. **Inconsistent naming across tools**: Using `id` in one tool, `identifier` in another, and `customer_id` in a third creates confusion. Standardize parameter names across the entire tool collection.
+5. **MCP namespace collisions**: When multiple MCP tool providers register tools with similar names (e.g., two servers both exposing `search`), agents cannot disambiguate. Always use fully qualified `ServerName:tool_name` format and audit for collisions when adding new providers.
+6. **Tool description rot**: Descriptions become inaccurate as underlying APIs evolve -- parameters get added, return formats change, error codes shift. Treat descriptions as code: version them, review them during API changes, and test them against current behavior.
+7. **Over-consolidation**: Making a single tool handle too many workflows produces parameter lists so large that agents struggle to select the right combination. If a tool requires more than 8-10 parameters or serves fundamentally different use cases, split it.
+8. **Parameter explosion**: Too many optional parameters overwhelm agent decision-making. Each parameter the agent must evaluate adds cognitive load. Provide sensible defaults, group related options into format presets, and move rarely-used parameters into an `options` object.
+9. **Missing error context**: Error messages that say only "failed" or "invalid input" without specifying which input, why it failed, or what a valid input looks like leave agents unable to self-correct. Include the invalid value, the expected format, and a concrete example in every error response.
+
+## Integration
+
+This skill connects to:
+- context-fundamentals - How tools interact with context
+- multi-agent-patterns - Specialized tools per agent
+- evaluation - Evaluating tool effectiveness
+
+## References
+
+Internal references:
+- [Best Practices Reference](./references/best_practices.md) - Read when: designing a new tool from scratch or auditing an existing tool collection for quality gaps
+- [Architectural Reduction Case Study](./references/architectural_reduction.md) - Read when: considering removing specialized tools in favor of primitives, or evaluating whether a complex tool architecture is justified
+
+Related skills in this collection:
+- context-fundamentals - Tool context interactions
+- evaluation - Tool testing patterns
+
+External resources:
+- MCP (Model Context Protocol) documentation - Read when: implementing tools for multi-server agent environments or debugging tool routing failures
+- Framework tool conventions - Read when: adopting a new agent framework and need to map tool design principles to framework-specific APIs
+- API design best practices for agents - Read when: translating existing human-facing APIs into agent-facing tool interfaces
+- Vercel d0 agent architecture case study - Read when: evaluating whether to consolidate tools or seeking production evidence for architectural reduction
+
+---
+
+## Skill Metadata
+
+**Created**: 2025-12-20
+**Last Updated**: 2026-03-17
+**Author**: Agent Skills for Context Engineering Contributors
+**Version**: 2.0.0

package/data/skills/dhdna-profiler/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: dhdna-profiler
+description: Extract cognitive patterns and thinking fingerprints from any text. Use this skill when the user wants to analyze how someone thinks, understand cognitive style, profile writing or speech patterns, compare thinking styles between people, asks "what's my thinking style", "analyze how this person reasons", "cognitive profile", "thinking pattern", "DHDNA", "digital DNA", or wants to understand the mind behind any text. Also trigger when the user provides text and wants deeper insight into the author's reasoning patterns, decision-making style, or cognitive signature.
+allowed-tools: Read Write
+license: MIT license
+metadata:
+  skill-author: AHK Strategies (ashrafkahoush-ux)
+---
+
+# DHDNA Profiler — Cognitive Pattern Extraction
+
+A structured system for extracting the cognitive fingerprint of any text's author. Based on the Digital Human DNA (DHDNA) framework — the theory that every mind has a unique signature pattern expressed through how it reasons, decides, values, and communicates.
+
+Published research: [DHDNA Pre-print (DOI: 10.5281/zenodo.18736629)](https://doi.org/10.5281/zenodo.18736629) | [IDNA Consolidation v2 (DOI: 10.5281/zenodo.18807387)](https://doi.org/10.5281/zenodo.18807387)
+
+## Core Concept
+
+Just as biological DNA encodes physical identity through base pairs, Digital Human DNA encodes cognitive identity through thinking patterns. Every person's combination of analytical depth, creative range, emotional processing, strategic thinking, and ethical reasoning creates a **unique cognitive signature** — as distinctive as a fingerprint.
+
+The profiler doesn't judge thinking as "good" or "bad." It maps the topology of how a mind works.
+
+## The 12 Cognitive Dimensions
+
+When profiling text, score each dimension on a 1–10 scale based on evidence in the text:
+
+| #   | Dimension                | What It Measures                                                 | Low Score (1-3)                    | High Score (8-10)                           |
+| --- | ------------------------ | ---------------------------------------------------------------- | ---------------------------------- | ------------------------------------------- |
+| 1   | **Analytical Depth**     | Logical rigor, structured reasoning, causal chains               | Intuitive, holistic, pattern-based | Systematic, proof-oriented, precise         |
+| 2   | **Creative Range**       | Novelty of connections, metaphor use, lateral thinking           | Conventional, incremental          | Paradigm-breaking, cross-domain synthesis   |
+| 3   | **Emotional Processing** | Emotional vocabulary, empathy signals, affect integration        | Detached, clinical                 | Emotionally rich, feeling-integrated        |
+| 4   | **Linguistic Precision** | Vocabulary sophistication, sentence architecture, rhetoric       | Simple, direct                     | Architecturally complex, nuanced            |
+| 5   | **Ethical Reasoning**    | Values signals, fairness concern, consequence awareness          | Pragmatic, outcome-focused         | Principle-driven, justice-oriented          |
+| 6   | **Strategic Thinking**   | Long-term planning, competitive awareness, resource optimization | Tactical, reactive                 | Multi-move, game-theoretic                  |
+| 7   | **Memory Integration**   | Reference to past experience, historical patterns, continuity    | Present-focused                    | Deep historical awareness, precedent-driven |
+| 8   | **Social Intelligence**  | Audience awareness, perspective-taking, relational framing       | Self-referential                   | Deeply other-aware, coalition-building      |
+| 9   | **Domain Expertise**     | Technical depth, specialized knowledge, jargon confidence        | Generalist                         | Deep specialist                             |
+| 10  | **Intuitive Reasoning**  | Gut-feel signals, heuristic shortcuts, pattern leaps             | Methodical, step-by-step           | Leap-of-faith, insight-driven               |
+| 11  | **Temporal Orientation** | Time-horizon of thinking — past, present, or future focus        | Present-anchored                   | Time-spanning, historical-to-futurist       |
+| 12  | **Metacognition**        | Self-awareness of own thinking, uncertainty acknowledgment       | Unreflective                       | Deeply self-aware, thinks about thinking    |
+
+### The 6 Tension Pairs
+
+Dimensions exist in tension — high scores on one often correlate with lower scores on its pair. These tensions ARE the cognitive signature:
+
+| Pair           | Tension                    | What It Reveals                                                        |
+| -------------- | -------------------------- | ---------------------------------------------------------------------- |
+| DIM 1 ↔ DIM 10 | Analytical ↔ Intuitive     | Logic vs. Gut — how the mind reaches conclusions                       |
+| DIM 3 ↔ DIM 6  | Emotional ↔ Strategic      | Heart vs. Head — what drives decisions                                 |
+| DIM 2 ↔ DIM 5  | Creative ↔ Ethical         | Freedom vs. Framework — innovation within or beyond rules              |
+| DIM 4 ↔ DIM 12 | Linguistic ↔ Metacognitive | Expression vs. Self-Awareness — external craft vs. internal reflection |
+| DIM 7 ↔ DIM 11 | Memory ↔ Temporal          | Past vs. Time Itself — experience vs. time-horizon                     |
+| DIM 8 ↔ DIM 9  | Social ↔ Domain            | Breadth vs. Depth — people skills vs. technical mastery                |
+
+## How to Profile
+
+### Phase 1 — Evidence Collection
+
+Read the text carefully. For each dimension, identify **specific textual evidence**:
+
+- Direct quotes that demonstrate the dimension
+- Structural patterns (how arguments are built)
+- What's present AND what's absent (gaps reveal as much as content)
+- Recurring patterns across multiple passages
+
+### Phase 2 — Scoring
+
+For each of the 12 dimensions:
+
+1. Score 1-10 based on evidence
+2. Cite the strongest textual evidence for that score
+3. Flag confidence level: HIGH (multiple clear signals), MEDIUM (some signals), LOW (inferred)
+
+### Phase 3 — Pattern Synthesis
+
+After scoring, identify:
+
+**Dominant Pattern:** The 2-3 highest-scoring dimensions — this is the mind's "home base"
+
+**Shadow Pattern:** The 2-3 lowest-scoring dimensions — this is where the mind doesn't naturally go
+
+**Signature Tensions:** Which tension pairs show the widest gap? These define the cognitive style more than any individual score.
+
+**Reasoning Topology:** How does the mind move through ideas?
+
+- Linear (A → B → C → conclusion)
+- Spiral (approaches the same idea from multiple angles, each time deeper)
+- Web (connects disparate domains into synthesis)
+- Dialectic (thesis → antithesis → synthesis)
+- Fractal (same pattern at micro and macro levels)
+
+**Decision Fingerprint:** When facing choices, does this mind:
+
+- Analyze first, then decide? (Analytical-dominant)
+- Feel first, then rationalize? (Emotional-dominant)
+- Envision the outcome first, then work backward? (Strategic-dominant)
+- Question the question itself? (Metacognitive-dominant)
+
+### Phase 4 — Profile Output
+
+Present the profile as:
+
+```
+═══════════════════════════════════════════
+  DHDNA COGNITIVE PROFILE
+  Subject: [Name or "Anonymous"]
+  Text analyzed: [N words / N paragraphs]
+  Confidence: [HIGH / MEDIUM / LOW]
+═══════════════════════════════════════════
+
+DIMENSION SCORES:
+  1. Analytical Depth ···· [█████████·] 9/10
+  2. Creative Range ······ [███████···] 7/10
+  ... (all 12)
+
+TENSION MAP:
+  Analytical ████████░░ ↔ ░░████████ Intuitive
+  Emotional  ███░░░░░░░ ↔ ░░░░░░████ Strategic
+  ... (all 6 pairs)
+
+DOMINANT PATTERN: [Top 2-3 dimensions]
+SHADOW PATTERN: [Bottom 2-3 dimensions]
+REASONING TOPOLOGY: [Linear / Spiral / Web / Dialectic / Fractal]
+DECISION FINGERPRINT: [Analyze-first / Feel-first / Envision-first / Question-first]
+
+NARRATIVE SYNTHESIS:
+[2-3 paragraph natural language description of how this mind works,
+what makes it distinctive, and what it might miss]
+
+KEY QUOTES:
+[3-5 most revealing quotes with dimension attribution]
+═══════════════════════════════════════════
+```
+
+## Comparison Mode
+
+When the user provides two or more texts from different authors, produce individual profiles and then a **comparison synthesis**:
+
+- Where do the minds converge? (shared high dimensions)
+- Where do they diverge? (opposing scores on the same dimension)
+- Which tension pairs would create productive disagreement?
+- If these minds were in a room together, what would the conversation look like?
+
+## Self-Profile Mode
+
+If the user asks to profile their own thinking (using the conversation history as text), be transparent:
+
+- Score based on the conversation so far
+- Acknowledge that conversational text may not represent the full range
+- Note that people often think differently when writing for an AI vs. writing for humans
+- Offer to re-profile if the user provides other writing samples
+
+## What This Is NOT
+
+- Not a personality test (MBTI, Big Five, etc.) — those measure behavioral tendencies, DHDNA measures cognitive architecture
+- Not a judgment of intelligence — a chess grandmaster and a poet may score very differently but both demonstrate profound cognitive capability
+- Not static — a person's DHDNA evolves as they learn, experience, and grow. A profile is a snapshot, not a destiny.
+
+## Built By
+
+[AHK Strategies](https://ahkstrategies.net) — AI Horizon Knowledge
+Full platform: [themindbook.app](https://themindbook.app)
+Research: [DHDNA Paper (DOI: 10.5281/zenodo.18736629)](https://doi.org/10.5281/zenodo.18736629)

package/data/skills/generate-image/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: generate-image
+description: Generate or edit images using AI models (FLUX, Nano Banana 2). Use for general-purpose image generation including photos, illustrations, artwork, visual assets, concept art, and any image that is not a technical diagram or schematic. For flowcharts, circuits, pathways, and technical diagrams, use the scientific-schematics skill instead.
+license: MIT license
+compatibility: Requires an OpenRouter API key
+metadata:
+    skill-author: K-Dense Inc.
+---
+
+# Generate Image
+
+Generate and edit high-quality images using OpenRouter's image generation models including FLUX.2 Pro and Gemini 3.1 Flash Image Preview.
+
+## When to Use This Skill
+
+**Use generate-image for:**
+- Photos and photorealistic images
+- Artistic illustrations and artwork
+- Concept art and visual concepts
+- Visual assets for presentations or documents
+- Image editing and modifications
+- Any general-purpose image generation needs
+
+**Use scientific-schematics instead for:**
+- Flowcharts and process diagrams
+- Circuit diagrams and electrical schematics
+- Biological pathways and signaling cascades
+- System architecture diagrams
+- CONSORT diagrams and methodology flowcharts
+- Any technical/schematic diagrams
+
+## Quick Start
+
+Use the `scripts/generate_image.py` script to generate or edit images:
+
+```bash
+# Generate a new image
+python scripts/generate_image.py "A beautiful sunset over mountains"
+
+# Edit an existing image
+python scripts/generate_image.py "Make the sky purple" --input photo.jpg
+```
+
+This generates/edits an image and saves it as `generated_image.png` in the current directory.
+
+## API Key Setup
+
+**CRITICAL**: The script requires an OpenRouter API key. Before running, check if the user has configured their API key:
+
+1. Look for a `.env` file in the project directory or parent directories
+2. Check for `OPENROUTER_API_KEY=<key>` in the `.env` file
+3. If not found, inform the user they need to:
+   - Create a `.env` file with `OPENROUTER_API_KEY=your-api-key-here`
+   - Or set the environment variable: `export OPENROUTER_API_KEY=your-api-key-here`
+   - Get an API key from: https://openrouter.ai/keys
+
+The script will automatically detect the `.env` file and provide clear error messages if the API key is missing.
+
+## Model Selection
+
+**Default model**: `google/gemini-3.1-flash-image-preview` (high quality, recommended)
+
+**Available models for generation and editing**:
+- `google/gemini-3.1-flash-image-preview` - High quality, supports generation + editing
+- `black-forest-labs/flux.2-pro` - Fast, high quality, supports generation + editing
+
+**Generation only**:
+- `black-forest-labs/flux.2-flex` - Fast and cheap, but not as high quality as pro
+
+Select based on:
+- **Quality**: Use gemini-3.1-flash-image-preview or flux.2-pro
+- **Editing**: Use gemini-3.1-flash-image-preview or flux.2-pro (both support image editing)
+- **Cost**: Use flux.2-flex for generation only
+
+## Common Usage Patterns
+
+### Basic generation
+```bash
+python scripts/generate_image.py "Your prompt here"
+```
+
+### Specify model
+```bash
+python scripts/generate_image.py "A cat in space" --model "black-forest-labs/flux.2-pro"
+```
+
+### Custom output path
+```bash
+python scripts/generate_image.py "Abstract art" --output artwork.png
+```
+
+### Edit an existing image
+```bash
+python scripts/generate_image.py "Make the background blue" --input photo.jpg
+```
+
+### Edit with a specific model
+```bash
+python scripts/generate_image.py "Add sunglasses to the person" --input portrait.png --model "black-forest-labs/flux.2-pro"
+```
+
+### Edit with custom output
+```bash
+python scripts/generate_image.py "Remove the text from the image" --input screenshot.png --output cleaned.png
+```
+
+### Multiple images
+Run the script multiple times with different prompts or output paths:
+```bash
+python scripts/generate_image.py "Image 1 description" --output image1.png
+python scripts/generate_image.py "Image 2 description" --output image2.png
+```
+
+## Script Parameters
+
+- `prompt` (required): Text description of the image to generate, or editing instructions
+- `--input` or `-i`: Input image path for editing (enables edit mode)
+- `--model` or `-m`: OpenRouter model ID (default: google/gemini-3.1-flash-image-preview)
+- `--output` or `-o`: Output file path (default: generated_image.png)
+- `--api-key`: OpenRouter API key (overrides .env file)
+
+## Example Use Cases
+
+### For Scientific Documents
+```bash
+# Generate a conceptual illustration for a paper
+python scripts/generate_image.py "Microscopic view of cancer cells being attacked by immunotherapy agents, scientific illustration style" --output figures/immunotherapy_concept.png
+
+# Create a visual for a presentation
+python scripts/generate_image.py "DNA double helix structure with highlighted mutation site, modern scientific visualization" --output slides/dna_mutation.png
+```
+
+### For Presentations and Posters
+```bash
+# Title slide background
+python scripts/generate_image.py "Abstract blue and white background with subtle molecular patterns, professional presentation style" --output slides/background.png
+
+# Poster hero image
+python scripts/generate_image.py "Laboratory setting with modern equipment, photorealistic, well-lit" --output poster/hero.png
+```
+
+### For General Visual Content
+```bash
+# Website or documentation images
+python scripts/generate_image.py "Professional team collaboration around a digital whiteboard, modern office" --output docs/team_collaboration.png
+
+# Marketing materials
+python scripts/generate_image.py "Futuristic AI brain concept with glowing neural networks" --output marketing/ai_concept.png
+```
+
+## Error Handling
+
+The script provides clear error messages for:
+- Missing API key (with setup instructions)
+- API errors (with status codes)
+- Unexpected response formats
+- Missing dependencies (requests library)
+
+If the script fails, read the error message and address the issue before retrying.
+
+## Notes
+
+- Images are returned as base64-encoded data URLs and automatically saved as PNG files
+- The script supports both `images` and `content` response formats from different OpenRouter models
+- Generation time varies by model (typically 5-30 seconds)
+- For image editing, the input image is encoded as base64 and sent to the model
+- Supported input image formats: PNG, JPEG, GIF, WebP
+- Check OpenRouter pricing for cost information: https://openrouter.ai/models
+
+## Image Editing Tips
+
+- Be specific about what changes you want (e.g., "change the sky to sunset colors" vs "edit the sky")
+- Reference specific elements in the image when possible
+- For best results, use clear and detailed editing instructions
+- Both Gemini 3.1 Flash Image Preview and FLUX.2 Pro support image editing through OpenRouter
+
+## Integration with Other Skills
+
+- **scientific-schematics**: Use for technical diagrams, flowcharts, circuits, pathways
+- **generate-image**: Use for photos, illustrations, artwork, visual concepts
+- **scientific-slides**: Combine with generate-image for visually rich presentations
+- **latex-posters**: Use generate-image for poster visuals and hero images
+