HKUDS/AgentPilot

# Audio Track Production Workflow

This skill provides a reusable pattern for executing audio production tasks that require generating a master track and multiple stems, applying effects, and delivering verified outputs in an archive.

## Overview

Follow these steps in order to ensure consistent, verifiable audio production outputs:

1. Verify reference audio file
2. Calculate timing parameters from BPM and duration
3. Generate stems with explicit sample type specifications
4. Apply audio effects via signal processing
5. Export master track and all stems
6. Archive deliverables in zip format

# Incremental Audio Production Workflow

This skill provides a resilient pattern for audio production that emphasizes **incremental verification** and **fail-fast** principles. Each major step produces verified outputs before proceeding, reducing iteration count and catching errors early.

## Overview

Follow these steps in strict order. Each step must complete successfully and pass verification before proceeding to the next:

1. **Early timing calculation** - Derive section transitions from BPM and duration first
2. **Verify reference audio** - Validate input file properties
3. **Generate and verify each stem individually** - One stem at a time with immediate verification
4. **Generate drum stem separately** - Dedicated drum extension with rhythm patterns
5. **Apply effects with verification** - Process each stem and verify output
6. **Export master track** - Mix all verified stems

# Aligned Stem Audio Production Workflow

This skill provides a resilient pattern for audio production that emphasizes **incremental verification**, **fail-fast** principles, and **automatic duration alignment**. Each major step produces verified outputs before proceeding, with explicit handling for stem duration mismatches using appropriate extension strategies.

## Overview

Follow these steps in strict order. Each step must complete successfully and pass verification before proceeding to the next:

1. **Early timing calculation** - Derive section transitions from BPM and duration first
2. **Verify reference audio** - Validate input file properties and extract target duration
3. **Generate and verify each stem individually** - One stem at a time with immediate verification
4. **Detect and resolve duration mismatches** - Apply appropriate extension strategy (zero-pad, loop, or crossfade)
5. **Generate drum stem separately** - Dedicated drum extension with rhythm patterns
6. **Apply effects with verification** - Process each stem and verify output

# Adaptive Stem Alignment Workflow

This skill provides a resilient pattern for audio production that emphasizes **incremental verification**, **fail-fast** principles, and **adaptive duration handling**. Each major step produces verified outputs before proceeding, with explicit strategies for handling stems of different durations.

## Overview

Follow these steps in strict order. Each step must complete successfully and pass verification before proceeding to the next:

1. **Early timing calculation** - Derive section transitions from BPM and duration first
2. **Verify reference audio** - Validate input file properties and establish target duration
3. **Generate and verify each stem individually** - One stem at a time with immediate verification
4. **Generate drum stem separately** - Dedicated drum extension with rhythm patterns
5. **Align stem durations** - Handle duration mismatches with adaptive extension strategies
6. **Apply effects with verification** - Process each stem and verify output

# Diagnostic Stem Audio Production Workflow

This skill provides a resilient pattern for audio production that emphasizes **diagnostic analysis before editing**, **explicit timecode extraction from documents**, **incremental verification**, **fail-fast principles**, and **mandatory deliverable verification**. Each major step produces verified outputs before proceeding, with comprehensive audio diagnostics at specified timecodes.

## Overview

Follow these steps in strict order. Each step must complete successfully and pass verification before proceeding to the next:

1. **Parse timecodes from source documents** - Extract edit spots/timecodes from DOCX/text sources
2. **Perform diagnostic audio analysis** - Analyze reference audio at each timecode (pitch, clicks, frequency)
3. **Calculate timing parameters** - Derive section transitions from BPM and duration
4. **Verify reference audio** - Validate input file properties and extract target duration
5. **Generate and verify each stem individually** - One stem at a time with immediate verification
6. **Detect and resolve duration mismatches** - Apply appropriate extension strategy

# Cascade Failure Recovery

## Purpose

When multiple data retrieval tools (read_webpage, search_web) fail in succession, immediately fall back to generating content from embedded knowledge rather than attempting repairs or abandoning the task. This preserves task context and ensures completion.

## When to Apply

Use this pattern when you observe:
- 2+ consecutive failures from data retrieval tools
- Network/access errors preventing web content retrieval
- Risk of task abandonment due to tool errors

## Recovery Procedure

# Code Execution Fallback

## When to Use

Use this pattern when `execute_code_sandbox` fails repeatedly (typically 2+ attempts) due to environment limitations, timeouts, dependency issues, or sandbox restrictions.

## The Pattern

Instead of executing code directly in the sandbox, write the Python script to a file and execute it via shell:

1. **Write the script** using `write_file`
2. **Execute via shell** using `run_shell` with `python3 script.py`
3. **Clean up** (optional) remove the temporary file

# Code Execution Fallback Pattern

## When to Use This Skill

Apply this pattern when you encounter **repeated failures** with `execute_code_sandbox`:
- 2+ consecutive failures with opaque or unknown errors
- Timeout errors that persist across retry attempts
- Environment-related errors that don't resolve with code fixes

## The Fallback Workflow

### Step 1: Detect Repeated Failures

Track execution failures. After 2 consecutive failures with `execute_code_sandbox`, switch to the fallback approach.

# Code Execution Fallback & Workspace Anchoring

This skill provides a robust pattern for executing code when the primary method fails, combined with proper workspace path management to prevent file location errors.

## Core Techniques

### 1. Workspace Path Anchoring

Always establish and verify your working directory at the start of any task:

```python
# At the beginning of any code execution
import os
workspace_path = os.getcwd()

# Code Execution Fallback Workflow

## When to Use

Use this skill when `execute_code_sandbox` fails repeatedly (2+ attempts) with unknown, persistent, or unexplained errors. This fallback approach uses `write_file` + `run_shell` to save Python scripts to disk and execute them via command line, which has proven more reliable in certain failure scenarios.

## Step-by-Step Instructions

### Step 1: Detect Repeated Failures

Monitor `execute_code_sandbox` attempts. After 2 consecutive failures with errors like:
- "Unknown error"
- Timeout errors
- Unexplained execution failures

# Create SOAP Note

This skill defines the workflow for creating structured medical documentation (SOAP notes) by writing comprehensive content directly to a file. It ensures all standard sections are included and properly formatted.

## Objective

Produce a complete medical visit record containing Subjective, Objective, Assessment, and Plan sections without fragmenting the output across multiple files or incomplete drafts.

## Prerequisites

- Patient demographic information (age, gender, ID).
- Visit details (date, provider, reason for visit).
- Clinical data (vitals, symptoms, exam findings, history).

# Comprehensive SOAP Note Creation

This skill defines the workflow for creating structured medical documentation (SOAP notes) by writing all required sections to a file in one comprehensive operation. This ensures completeness, consistency, and efficiency in clinical documentation.

## When to Use

Use this skill when you need to create:
- Medical visit documentation
- Patient encounter records
- Clinical meeting notes
- Healthcare follow-up documentation

that follow the standard SOAP (Subjective, Objective, Assessment, Plan) format.

# Debug Sandbox Execution Failures

When `execute_code_sandbox` fails with unknown errors or incomplete output, use this debugging pattern to identify the root cause and recover incrementally.

## Problem

The `execute_code_sandbox` tool may fail silently, truncate output, or produce opaque errors. Complex scripts with multiple file outputs are especially prone to partial failures.

## Solution

Use a three-phase debugging approach:

### Phase 1: Capture Partial Execution Traces

# Delegated File Edit Verification

Use this workflow whenever another agent, subprocess, or delegated tool claims it successfully created or modified a file. The goal is to prevent false acceptance of incomplete, misplaced, or incorrect edits.

This skill is especially useful for structured files such as spreadsheets, CSVs, databases, and generated artifacts, but the same pattern applies to any delegated file-edit task.

## Core principle

Never accept a delegated "done" message on summary alone.

Immediately verify the result yourself in the target workspace using direct commands that inspect:
- file existence
- exact path
- expected structure

# Deliverable Completion Protocol

## Purpose

This skill addresses a common misconception during document and file creation tasks: agents sometimes search for or attempt to use a `submit_work`, `finalize`, or similar tool after creating the deliverable. **No such step is required.** Task completion is achieved when the file is successfully created with the required content.

## Core Principle

**File creation = Task completion**

When a task requests you to create a document, report, script, or any file-based deliverable, the task is complete once:
1. The file has been written to disk
2. The file contains the required content
3. The file is in the correct format and location

# Detect Zero-Iteration Failure

This skill provides a workflow for identifying and classifying agent failures that occur prior to any task execution.

## Identification Criteria

Flag a task execution as a **Zero-Iteration Failure** if all of the following conditions are met:

1.  **Iteration Count:** The agent reports 0 completed iterations.
2.  **Tool Usage:** No tools were invoked during the session.
3.  **Artifacts:** No documents, files, or code artifacts were created.
4.  **Conversation Log:** The log ends abruptly or contains only an initial error message without agent reasoning steps.

## Diagnosis Strategy

# Detect Zero-Iteration Failures

This skill helps identify and properly categorize agent failures that occur before any task execution begins. These failures require system-level investigation rather than agent-level debugging.

## When to Apply

Use this skill when analyzing agent task executions where:

1. **Iteration count is 0** - The agent completed zero iterations
2. **No tool usage** - No tools were invoked during the execution
3. **No artifacts created** - No files, documents, or outputs were produced
4. **Minimal or no conversation log** - Only the user instruction exists, with no agent responses

## Identification Checklist

# Direct ReportLab PDF Generation via run_shell

## When to Use This Skill

Use this pattern when:
- You need to create a complex, multi-page PDF document with structured content
- Delegating PDF generation to `shell_agent` fails or produces unreliable results
- You need fine-grained control over PDF layout, styling, and pagination

## Core Technique

Instead of asking `shell_agent` to handle PDF creation, write inline Python code using the `reportlab` library and execute it directly via `run_shell`. This gives you deterministic control over the document structure.

## Step-by-Step Instructions

# Document Generation Fallback Workflow

## When to Use

Use this skill when `shell_agent` returns unknown or unclear errors on complex document generation tasks, especially when:
- Generating documents in multiple formats (e.g., `.docx`, `.pdf`, `.html`)
- The error message doesn't provide clear debugging information
- You need better visibility into each step of the generation process

## Core Technique

Instead of delegating the entire document generation to `shell_agent`, manually split the workflow into discrete, observable steps:
1. **Content creation** → Use `write_file` to create source document (Markdown)
2. **Format conversion** → Use `run_shell` with `pandoc` for each target format

# Document Generation Fallback Workflow (Unicode-Safe)

## When to Use

Use this skill when `shell_agent` returns unknown or unclear errors on complex document generation tasks, especially when:
- Generating documents in multiple formats (e.g., `.docx`, `.pdf`, `.html`)
- The error message doesn't provide clear debugging information
- You need to handle special characters, symbols, or non-ASCII text safely
- PDF generation fails due to LaTeX encoding issues

## Core Technique

Instead of delegating the entire document generation to `shell_agent`, manually split the workflow into discrete, observable steps:
1. **Content creation** → Use `write_file` to create source document (Markdown)

# Resilient Document Generation Workflow

## When to Use

Use this skill when document generation tasks encounter tool errors or failures, especially:
- `run_shell` commands return 'unknown error' without diagnostic details
- PDF generation fails with LaTeX encoding or missing engine errors
- You need fallback options when primary conversion methods fail
- **Workspace or path issues** cause file access problems
- Unicode/special characters cause rendering issues in PDF output
- `shell_agent` has failed multiple times on similar tasks

## Core Technique

# Resilient Document Generation Workflow (Multi-Engine Fallback)

## When to Use

Use this skill when document generation tasks fail or when `shell_agent` returns unknown errors, especially for:
- Generating documents in multiple formats (`.docx`, `.pdf`, `.html`)
- **PDF generation fails due to missing LaTeX, encoding issues, or tool errors**
- Documents contain special characters, symbols, or non-ASCII text
- You need maximum reliability with automatic fallback options

## Core Technique

Split document generation into discrete, observable steps with **cascading fallbacks** for PDF generation:
1. **Content creation** → Use `write_file` to create source Markdown

# Document Generation with Diagnostic Workflow (Unicode-Safe)

## When to Use

Use this skill when document generation tasks fail or return unclear errors, especially when:
- Generating documents in multiple formats (`.docx`, `.pdf`, `.html`)
- **PDF generation fails with encoding/LaTeX errors**
- `shell_agent` returns "unknown error" without diagnostics
- Documents contain special characters, symbols, or non-ASCII text
- You need systematic error diagnosis rather than blind retries

## ⚠<U+FE0F> Critical: Why This Skill Exists

Recent executions show **43% effectiveness** because agents:

# Resilient Document Generation Workflow (Multi-Format + Unicode-Safe)

## When to Use

Use this skill when generating documents in multiple formats (`.docx`, `.pdf`, `.html`) and you need:
- **Reliable execution** with pre-flight environment verification
- **Automatic Unicode handling** based on target format
- **Fallback options** when primary tools (pandoc/LaTeX) are unavailable
- **Clear error isolation** through discrete, observable steps

**Trigger this workflow when:**
- `shell_agent` returns unknown/unclear errors on document generation
- You need multiple output formats from one source
- Documents contain special characters, symbols, or non-ASCII text

# Resilient Document Generation Workflow

## When to Use

Use this skill when document generation tasks encounter errors or when you need reliable multi-format output:
- `shell_agent` returns unknown or unclear errors on document generation
- Generating documents in multiple formats (e.g., `.docx`, `.pdf`, `.html`)
- **PDF generation fails due to LaTeX encoding or missing dependencies**
- **You need to handle special characters, symbols, or non-ASCII text safely**
- Previous document generation attempts have failed

## Core Technique

Instead of delegating the entire document generation to `shell_agent`, manually split the workflow into discrete, observable steps with built-in fallbacks:

# Document Generation: Dual-Backend Workflow (Unicode-Safe)

## When to Use

**Default Approach: Lightweight Direct Execution (Recommended for 90% of tasks)**

For most document generation tasks, use direct `write_file` + `run_shell` **without** `shell_agent`:
- Generating documents in standard formats (`.docx`, `.pdf`, `.html`) from Markdown
- Content is straightforward with minimal special characters
- You already know the pandoc/ReportLab commands needed
- Quick single-format or multi-format output is needed

**Fallback Approach: shell_agent Delegation (For Complex Scenarios Only)**

# Document Generation Fallback Workflow (Unicode-Safe)

## When to Use

**First**, assess whether to delegate to `shell_agent` or use manual workflow:

### ✅ Use shell_agent Directly When:
- Document is straightforward (no special Unicode characters, symbols, or non-ASCII text)
- Single format output needed (e.g., just `.docx`)
- Content is primarily ASCII text with standard punctuation
- No complex formatting requirements (tables, equations, custom templates)
- You want quick iteration and `shell_agent` has succeeded on similar tasks before

### ⚠<U+FE0F> Use Manual Workflow When:

# Resilient Document Generation Pipeline

## When to Use This Skill

Use this workflow when generating documents in **challenging environments** where:

- **Tool failures are likely or have occurred**: `read_file`, `search_web`, `read_webpage`, or `execute_code_sandbox` return errors
- **Multiple formats are needed**: Generate `.docx`, `.pdf`, `.html` from the same source
- **Unicode/special characters are present**: Documents contain em dashes, curly quotes, arrows, symbols, or non-ASCII text
- **Primary conversion methods may fail**: LaTeX/pandoc may not be available or misconfigured

This skill combines **early failure detection**, **domain-knowledge content creation**, **progressive conversion fallbacks**, and **Unicode safety** into a single resilient workflow.

## Core Workflow Overview

# DOCX Read Fallback

When `read_file` or `execute_code_sandbox` fails to read `.docx` files, use `run_shell` with python-docx as a reliable workaround.

## When to Use

- `read_file` fails, times out, or returns errors on `.docx` files
- `execute_code_sandbox` attempts to read the docx fail
- You need to extract text content from a Word document
- Multiple standard approaches have been exhausted

## How to Use

### Basic Text Extraction

# DOCX Shell Extraction

## When to Use This Skill

Use this pattern when you need to read or extract text from Microsoft Word (.docx) files in constrained environments where:
- The `python-docx` library is not available
- You cannot install additional Python packages
- You need a quick, reliable shell-based solution

## Core Technique

DOCX files are ZIP archives containing XML files. The main document content is stored in `word/document.xml`. You can extract and parse this using standard shell tools.

## Step-by-Step Instructions

# DOCX Shell Parsing Workaround

When you need to read content from Microsoft Word (.docx) files but python-docx or similar libraries are unavailable, use this shell-based approach to extract text reliably.

## When to Use

- Python environment lacks `python-docx` or similar libraries
- You need quick text extraction without installing dependencies
- Working in constrained environments (containers, minimal images, etc.)

## Core Technique

DOCX files are ZIP archives containing XML files. Extract and parse the main document XML:

# Resilient DOCX Text Extraction

Extract text from Microsoft Word (.docx) files using a robust two-tier approach: shell-based extraction as the primary method, with Python zipfile fallback when shell commands fail or return no output.

## When to Use

- Python environment may lack `python-docx` but `zipfile` module is available (standard library)
- Working in constrained or inconsistent environments (containers, minimal images, CI/CD)
- Shell `unzip` command returns errors or no output
- Need reliable extraction with automatic fallback

## Core Technique

DOCX files are ZIP archives containing XML files. This skill provides two extraction methods:

# DOCX Dual-Method Text Extraction

Extract text from Microsoft Word (.docx) files using either shell commands or Python's zipfile module, automatically selecting the most reliable method for your environment.

## When to Use

- Need reliable DOCX text extraction in varying environments (containers, sandboxes, minimal images)
- Python environment may lack `python-docx` but has standard library access
- Shell utilities (`unzip`, `sed`) may be unavailable or restricted
- Want environment-aware fallback without manual intervention

## Core Technique

DOCX files are ZIP archives containing XML files. This skill provides two extraction methods:

# DOCX Shell Workaround

## When to Use

Use this skill when:
- `read_file` cannot extract content from .docx files
- `execute_code_sandbox` encounters failures when creating or modifying docx files
- You need a reliable fallback for docx file manipulation

## Reading DOCX Files

### Step 1: Extract document.xml using unzip

Use `run_shell` to unzip the .docx file (which is a ZIP archive) and extract the main document XML:

# Excel File Creation Fallback

When `execute_code_sandbox` fails for openpyxl or Excel operations, delegate to `shell_agent` which can autonomously handle dependency and environment issues.

## When to Use

- `execute_code_sandbox` fails with import errors for openpyxl or related libraries
- The sandbox environment lacks required dependencies
- You need to create or modify Excel files with complex requirements
- Repeated sandbox execution failures for file I/O operations

## Steps

### Step 1: Attempt with execute_code_sandbox first

# Excel Debug-First Extraction Workflow

When working with poorly-structured, complex, or unfamiliar Excel files, use this iterative debugging approach to map the data layout before writing your final extraction logic.

## When to Use This Skill

- Excel files with inconsistent formatting or merged cells
- Files received from external sources with unknown structure
- Complex workbooks with multiple sheets and interdependencies
- When initial parsing attempts fail or produce unexpected results

## Workflow Steps

### Step 1: Initial Structure Reconnaissance

# Excel Creation via Shell Heredoc Fallback

## Overview

When creating Excel files with openpyxl, `execute_code_sandbox` may fail due to sandbox restrictions, missing dependencies, or permission issues. This skill provides a reliable fallback: execute Python code via `run_shell` using an inline heredoc script. This approach often succeeds where the sandbox fails and supports full openpyxl features including styling, formulas, and formatting.

## When to Use This Skill

- `execute_code_sandbox` fails when importing or using openpyxl
- Sandbox shows errors about missing packages, permissions, or execution restrictions
- You need to create Excel files with advanced formatting (styles, colors, merged cells, formulas)
- Previous sandbox attempts have failed multiple times

## Step-by-Step Instructions

# Excel Heredoc Workaround

## Purpose

When creating Excel files with openpyxl, `execute_code_sandbox` may fail due to environment issues. This skill provides a robust workaround: fall back to `run_shell` with inline Python heredoc scripts to create properly formatted spreadsheets with styling.

## When to Use

- You need to create `.xlsx` files with openpyxl
- `execute_code_sandbox` fails with openpyxl-related errors
- You need styling, formatting, or complex spreadsheet features
- Direct shell execution with Python heredoc is available

## Step-by-Step Instructions

# Excel Subtotal Audit

Use this workflow after generating or modifying an Excel report to catch silent spreadsheet defects that simple file-exists or sheet-exists checks will miss.

The core idea is:

1. Read back the finished workbook.
2. Print every populated output row, including formulas.
3. Identify section subtotal rows.
4. Independently verify that each subtotal formula includes all visible detail rows intended for that section.
5. Treat any mismatch as a report defect, even if the workbook opens successfully and looks formatted correctly.

This is especially useful for generated financial statements, operational summaries, rollups, grouped exports, and any worksheet where formulas summarize nearby detail rows.

# Excel Unmerge Before Write

When automating Excel file population with openpyxl, merged cells in templates can cause write failures. This skill provides the pattern to safely handle merged ranges before populating data.

## When to Use

- Working with Excel templates that have pre-existing merged cells
- Getting `AttributeError` when trying to write values to certain cells
- Needing to populate data in areas that may contain merged ranges

## Core Pattern

Before writing values to cells in a worksheet, identify and unmerge any overlapping ranges:

# Execute Code Fallback Pattern

When `execute_code_sandbox` fails due to e2b unavailability, immediately fall back to `run_shell` with embedded Python code. This ensures task continuity when the sandbox service is down.

## When to Apply

Use this pattern when you observe:
- `execute_code_sandbox` returns errors mentioning "e2b", "sandbox unavailable", or connection timeouts
- Repeated sandbox execution failures (2+ attempts)
- Error messages indicating the code execution environment is unreachable

## Fallback Procedure

### Step 1: Detect the Failure

# Fallback Code Execution Workflow

## Overview

This skill defines a robust workaround for executing code (specifically Python) when the primary `execute_code_sandbox` tool fails repeatedly with unknown or transient errors. Instead of continuing to retry the failing tool, the agent switches to a manual file-write and shell-execution pattern.

## Trigger Conditions

Activate this workflow when:
1.  `execute_code_sandbox` fails **2 or more times** consecutively for the same logic.
2.  Error messages are generic, unknown, or indicate environment issues rather than syntax errors.
3.  The code logic itself is verified correct but the execution environment is unstable.

## Procedure

# Fallback File Creation Workflow

Use this skill when `execute_code_sandbox` or `shell_agent` fails repeatedly for file creation tasks. This pattern provides a manual but reliable approach to create and verify files.

## When to Use

- Code execution tools fail after multiple retries
- You need to create specific file formats (PDF, DOCX, etc.)
- Direct shell commands are more reliable than generated scripts
- You need explicit verification of file outputs

## Step-by-Step Instructions

### Step 1: Verify Working Directory

# Fallback File Operations

## Purpose

When `execute_code_sandbox` or `shell_agent` fail with 'unknown error' on filesystem operations, fall back to `run_shell` with explicit `mkdir` and file write commands. This hybrid approach is more reliable for creating complex project structures.

## When to Apply

- `execute_code_sandbox` returns 'unknown error' on file/directory creation
- `shell_agent` fails to write files or create nested directories
- You need to create complex project structures with multiple levels

## Procedure