Authoring Custom Workflow Scripts
Relevant source files
The following files were used as context for generating this wiki page:
Authoring custom workflow scripts is a core capability within the Continuous Claude project, allowing developers to create agent-agnostic, reusable Python-based workflows that orchestrate Model Context Protocol (MCP) tools. Unlike native "Skills" which are specific to Claude Code, "Scripts" are CLI-based utilities designed for high token efficiency and cross-agent compatibility.
These scripts serve as templates for complex logic, multi-tool chaining, and data processing pipelines. By utilizing command-line arguments (via argparse), they achieve up to a 99.6% reduction in token overhead compared to manual tool invocation by an AI agent.
Sources: scripts/README.md:1-25, scripts/SCRIPTS.md:1-15, CLAUDE.md:1-10
Architecture and Execution Model
The script architecture relies on a specialized execution harness (runtime.harness) that initializes the MCP environment, manages signal handlers, and handles cleanup.
Workflow Execution Flow
The following diagram illustrates how a script is discovered and executed by an agent or user:
The execution process prioritizes reading documentation (docstrings) to understand available CLI arguments before invocation.
Sources: CLAUDE.md:118-125, scripts/SCRIPTS.md:30-45
Key Components
| Component | Description | Location |
|---|---|---|
| Execution Harness | Asyncio-based runner that manages MCP lifecycle and signals. | src/runtime/harness.py |
| MCP Client Manager | Singleton that handles lazy loading and on-demand tool connections. | src/runtime/mcp_client.py |
| Python Wrappers | Pydantic-validated wrappers generated for each tool. | servers/<server>/ |
| Argparse | Standard library used for parameter passing to scripts. | Script-specific |
Sources: CLAUDE.md:143-155, scripts/README.md:10-15
Development Guidelines
The Script Template
Custom scripts must follow a specific structural pattern to ensure compatibility with the runtime.harness and provide clear instructions to AI agents.
"""
SKILL: {Name}
DESCRIPTION: {What it does}
CLI ARGUMENTS:
--param Description
USAGE:
uv run python -m runtime.harness scripts/your_script.py --param "value"
"""
import argparse
import asyncio
import sys
def parse_args():
parser = argparse.ArgumentParser()
parser.add_argument("--param", required=True)
# Filter out script path added by harness
args_to_parse = [arg for arg in sys.argv[1:] if not arg.endswith(".py")]
return parser.parse_args(args_to_parse)
async def main():
args = parse_args()
# Logic goes here
return result
if __name__ == "__main__":
asyncio.run(main())
Sources: scripts/README.md:75-102, scripts/SCRIPTS.md:65-95
Tool Orchestration Logic
Scripts often chain multiple tools together. The call_mcp_tool function is the primary interface for interacting with configured MCP servers.
The tool_id follows the naming convention "serverName__toolName" (note the double underscore).
Sources: CLAUDE.md:160-165, scripts/multi_tool_pipeline.py:40-65
Comparison: Scripts vs. Skills
It is critical to distinguish between agent-agnostic Scripts and Claude Code-native Skills.
| Feature | Scripts (./scripts/) | Skills (.claude/skills/) |
|---|---|---|
| Format | Python with argparse | YAML + Markdown (SKILL.md) |
| Execution | CLI-based parameters | Native prompt triggers |
| Compatibility | Any AI Agent | Claude Code Only |
| Efficiency | 99.6% token reduction | Progressive disclosure focus |
| Discovery | Manual (ls, cat) | Automatic (Scanned by agent) |
Sources: scripts/README.md:50-65, CLAUDE_ONBOARDING.md:40-55
Best Practices for Authoring
- Parameter Immutability: Always use
argparsefor configurable values. Avoid editing the script's code to change execution parameters. - Logic Mutability: Developers are encouraged to edit script logic to fix bugs, improve processing, or refine tool-chaining flows.
- Argument Filtering: Always filter
sys.argvto remove the script path, as the harness may prepend it:[arg for arg in sys.argv[1:] if not arg.endswith(".py")]. - Structured Output: Scripts should return structured data (dictionaries or Pydantic models). The agent can then summarize or process this raw data as needed.
- Defensive Coding: When interacting with auto-generated wrappers, use defensive checks for optional fields or potentially missing data in API responses.
Sources: scripts/SCRIPTS.md:135-150, CLAUDE.md:180-195, src/runtime/generate_wrappers.py:100-110
Conclusion
Authoring custom workflow scripts enables the creation of complex, high-performance automation within the Continuous Claude ecosystem. By standardizing on CLI-based Python scripts, the project ensures that complex multi-step operations are handled with minimal token consumption and maximum reliability across different AI interaction sessions.