DS-STAR Data Science Framework

DS-STAR (Data Science - Structured Thought and Action) is an intelligent multi-agent framework designed to transform raw data into actionable insights directly within Claude Code. By orchestrating seven specialized agents—ranging from data analyzers to Python coders and verifiers—the framework manages the entire data science lifecycle, from initial exploratory data analysis to iterative debugging and final validation. It dramatically optimizes performance and cost by dynamically routing tasks to the most suitable Claude model (Haiku, Sonnet, or Opus), achieving up to 60% savings compared to single-model approaches.

Originally designed for Google's Gemini models, this skill adapts DS-STAR to leverage Anthropic's Claude model family. It automates complex data science workflows through structured collaboration, making it a reproducible and highly efficient alternative to manual data investigation.

DS-STAR orchestrates seven specialized agents in an iterative execution loop to solve data questions:

┌─────────────────────────────────────────────────────────┐
│  1. ANALYZER (Haiku)                                    │
│     Input: Data files                                   │
│     Output: Data descriptions, schemas, summaries       │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│  2. PLANNER (Sonnet)                                    │
│     Input: Query + Data descriptions                    │
│     Output: Initial analysis step                       │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│  3. CODER (Sonnet)                                      │
│     Input: Plan + Data descriptions                     │
│     Output: Python code to execute plan                 │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│  4. DEBUGGER (Sonnet) [If needed]                       │
│     Input: Code + Error                                 │
│     Output: Fixed code                                  │
└─────────────────────────────────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────────┐
│  5. VERIFIER (Sonnet)                                   │
│     Input: Code + Results + Query                       │
│     Output: "Sufficient" or "Needs refinement"          │
└─────────────────────────────────────────────────────────┘
                         ↓
           ┌─────────────┴─────────────┐
           │    Sufficient?            │
           └─────────────┬─────────────┘
                 YES │   │ NO
                     │   └──────────────┐
                     │                  ↓
                     │    ┌──────────────────────────────┐
                     │    │  6. ROUTER (Haiku)           │
                     │    │     Decide: Fix step or Add  │
                     │    └──────────────────────────────┘
                     │                  │
                     │                  ↓
                     │         [Loop back to PLANNER]
                     │
                     ↓
┌─────────────────────────────────────────────────────────┐
│  7. FINALYZER (Sonnet)                                  │
│     Input: Final code + Results + Query                 │
│     Output: Formatted answer (JSON/text)                │
└─────────────────────────────────────────────────────────┘

• Iterative Refinement: DS-STAR uses up to 5 refinement rounds (user-configurable). Each round can add a new analysis step or correct a previous step.
• Verification Gates: Automated gates prevent poor outputs, with automatic debugging retries for failed code.
• Artifact Generation: Full logging saves prompts, generated code, and results to runs/<run_id>/ for audit trails and complete reproducibility.

1. Comprehensive Artifact Generation: Automatically saves prompts, execution code, and runtime logs for research reproducibility.
2. Cost-Optimized Model Routing: Strategically routes sub-tasks across Haiku, Sonnet, and Opus, reducing analysis expenses by up to 60%.
3. Iterative Refinement Cycles: Implements automated debugging and rigorous verification gates to ensure high-accuracy results.
4. Multi-Agent Orchestration: Deploys specialized agent roles (Analyzer, Planner, Coder, Router, Verifier, Debugger, Finalyzer) to divide and conquer tasks.
5. Native Support for Diverse Formats: Handles structured and unstructured datasets, including CSV, JSON, and plain text files.

• Automating Exploratory Data Analysis (EDA): Swiftly generate statistical summaries and understand core distribution behaviors in new datasets.
• Cost-Effective Processing Workflows: Process large volumes of data using mixed-model logical patterns rather than relying entirely on expensive frontier models.
• Iterative Analysis & Debugging: Automatically run and refine multi-step time-series, predictive, or correlation analyses where initial attempts might encounter runtime exceptions.

By using a custom-built model routing strategy, DS-STAR limits resource consumption. Instead of routing all requests to Claude 3.5 Sonnet, simpler tasks (like data scheme scanning or routing choices) are directed to Claude 3 Haiku.

• Estimated Cost (Typical Analysis of ~50K tokens):
  • Traditional (Single-model Sonnet execution): ~$0.50 -$1.00
  • DS-STAR (Mixed-model execution): ~$0.20 -$0.40
  • Net Savings: 50% - 60%

• Use Haiku for: Core data file inspection (Analyzer), simple routing decisions (Router), and basic textual extraction.
• Use Sonnet for: Strategic planning (Planner), complex script generation (Coder), validating answers (Verifier), and finalizing responses (Finalyzer).
• Use Opus for: Complex edge-case debugging, highly sensitive financial/scientific analysis, and completely novel or ambiguous data formats.

To install the skill via the token-eater marketplace in Claude Code:

# Add the marketplace (if not already added)
/plugin marketplace add token-eater/skills-marketplace

# Install DS-STAR skill
/plugin install ds-star

To set up the skill manually from source:

# Clone the marketplace
git clone https://github.com/token-eater/skills-marketplace.git
cd skills-marketplace

# The skill code resides within skills/ds-star/

You can control framework settings using a config.yaml file placed in your project root, or declare them in your run query.

# config.yaml (optional, in project root)
run_id: "my_experiment"           # Custom run ID
model_name: "sonnet"               # Default model
interactive: false                 # Pause between steps for manual confirmation
max_refinement_rounds: 5           # Max iterations before stopping
execution_timeout: 60              # Code timeout in seconds
preserve_artifacts: true           # Save all outputs, steps, and scripts
runs_dir: "runs"                   # Directory path to write artifacts
data_dir: "data"                   # Directory where raw data is kept

# Agent-specific model overrides
agent_models:
  ANALYZER: haiku
  PLANNER: sonnet
  CODER: sonnet
  VERIFIER: sonnet
  ROUTER: haiku
  DEBUGGER: opus
  FINALYZER: sonnet

• Fast (70%+ cost savings): Runs all roles on Claude Haiku, except for the Coder and Debugger agents.
• Balanced (50% cost savings): Runs simple tasks on Haiku and complex reasoning/validation on Sonnet.
• Quality (Highest accuracy): Assigns all agent roles to Sonnet or Opus.

To run the skill within Claude Code, simply call:

/skill ds-star

The framework will prompt you interactively to provide:

1. The path to your data files (CSV, JSON, TXT, etc.).
2. Your analytical query.
3. Model preset configurations (optional).

• Basic Statistics:

  "What is the average age and gender distribution in this dataset?" (Data: customers.csv)

• Time Series Analysis:

  "What are the monthly sales trends over the past year?" (Data: sales_2024.csv)

• Data Quality Assesment:

  "How many missing values are in each column, and what percentage of the total?" (Data: survey_responses.csv)

• Correlation Analysis:

  "Which features have the strongest correlation with customer churn?" (Data: customer_features.csv)

• Data File: iris.csv (150 rows, 5 columns)
• Query: "What is the average petal length for each species, and which species has the highest variance?"
• Response Output:

{
  "final_answer": {
    "averages": {
      "setosa": 1.46,
      "versicolor": 4.26,
      "virginica": 5.55
    },
    "highest_variance": "virginica",
    "variance_value": 0.304
  }
}

• Metrics: Cost: $0.18 (Balanced configuration) | Time: ~25 seconds | Execution Steps: 3 (Analyze → Plan → Code → Verify → Finalize)

• Data File: sales_2024.csv (365 rows, daily sales tracking)
• Query: "Identify the top 3 months by total sales and calculate month-over-month growth rates."
• Response Output:

{
  "final_answer": {
    "top_3_months": [
      {"month": "December", "total_sales": 125000, "growth": "+15%"},
      {"month": "November", "total_sales": 108000, "growth": "+8%"},
      {"month": "July", "total_sales": 95000, "growth": "+12%"}
    ],
    "average_growth": "+8.3%"
  }
}

• Metrics: Cost: $0.22 (Balanced configuration) | Time: ~30 seconds | Execution Steps: 4 (Including 1 refinement round)

This skill features a custom ClaudeProvider that interfaces directly with the Claude Agent SDK, utilizing subagents for high context efficiency.

class ClaudeProvider(ModelProvider):
    """Provider for Claude models via Agent SDK."""

    def __init__(self, model_name: str = "sonnet"):
        self.model_name = model_name  # haiku, sonnet, or opus

    def generate_content(self, prompt: str) -> str:
        # Use SDK's subagent system for context efficiency
        # Automatically handles model routing
        # Returns generated content

• Context Efficient: Leverages subagents to eliminate large, monolithic context windows.
• Parallel Execution: Allows independent processes to evaluate data structures simultaneously.
• Artifact Persistence: All files are written directly into local directories.
• Resume Support: Interruptions do not force a restart. Resume a prior state using:

  /skill ds-star --resume 20241123_143022_a1b2c3
  

Every pipeline run generates a structured directory of inputs, intermediate decisions, and logs:

runs/<run_id>/
├── steps/
│   ├── 001_analyzer/
│   │   ├── prompt.md       # Target agent instructions
│   │   ├── code.py         # Output script generated by the agent
│   │   ├── result.txt      # Executed console output
│   │   └── metadata.json   # Step execution statistics and costs
│   ├── 002_planner_init/
│   ├── 003_coder/
│   └── ...
├── exec_env/               # Direct file execution runtime space
├── logs/
│   ├── pipeline.log        # High-level orchestrator system logs
│   └── execution.log       # Granular python subprocess compilation logs
├── final_output/
│   └── result.json         # Extracted JSON final answer
└── pipeline_state.json     # Checkpoint state dictionary for resuming

• Do:
  • Write clear, targeted prompts: "Calculate the Pearson correlation coefficient between columns X and Y."
  • Ask direct logic questions: "What percentage of customers have completed more than 3 purchases?"
  • Pinpoint outliers: "Identify outlier values in the 'price' column using the 1.5x IQR method."
• Avoid:
  • Broad, ambiguous requests: "Tell me something interesting about this data."
  • Overwhelming commands: "Do everything." Split massive multi-part requirements into independent query runs.
  • Referencing external, inaccessible sources: Do not request external databases, APIs, or files unless pre-loaded locally.

• Optimal Formats: Clean, standard .csv files containing structured header titles; consistent, unified nesting in .json documents; or plain UTF-8 encoded .txt data files.
• Problematic Formats: Multi-tab .xlsx workbooks (convert tabs to individual .csv files first); un-parsed .pdf documents; and raw binary inputs (images, audio files).

• Python-Only Execution: The system executes instructions by generating and running Python scripts using packages like pandas and numpy.
• Local Run Hazards: The code runs locally on your system. Be highly cautious when letting the tool run code generated from untrusted, third-party data inputs.
• No Outbound Network APIs: By design, running agents cannot hit external API endpoints or fetch live web information.
• Single Output Format: The finalization agent (Finalyzer) produces a single summary payload (JSON or TXT).
• No Interactive Charts: Real-time interactive visualizations and plotting are not supported (plots cannot be interactively rendered, though static files can be written).

1. "Missing data files" Error
   • Ensure target datasets are in the data/ subdirectory or provide absolute, fully qualified file paths.
   • Verify read permissions on target folders.
2. Execution Timed Out
   • If a python script hangs, adjust the execution_timeout in your config.yaml to a value higher than the default 60 seconds.
   • Simplify the target query or optimize large files (such as chunking).
3. "API key not found"
   • No API keys are required for built-in Claude models as long as the Claude Agent SDK handles authentication. External models (OpenAI/Gemini) will require standard environmental variables set in your local system.
4. Verification Gate Always Fails
   • Refine your prompt to be less ambiguous.
   • Increase the maximum allowable cycles using max_refinement_rounds: 10.
   • Check intermediate run scripts in runs/<id>/steps/ to pinpoint logic bottlenecks.

To manually inspect executions, enable interactive step pausing or analyze raw files:

# Run with interactive mode to pause and confirm before each step runs
/skill ds-star --interactive

# Inspect pipeline execution history manually
ls runs/<run_id>/steps/
cat runs/<run_id>/logs/pipeline.log

We welcome community extensions and framework iterations.

1. Define your custom agent profile inside scripts/dsstar.py.
2. Draft the agent's core instructions and prompt template within scripts/prompts.py.
3. Chain the agent into the execution loop inside the run_pipeline() method.
4. Verify functionality using your own data samples.
5. Create a Pull Request (PR) on GitHub.

• Visualization Agent: Create and save matplotlib or seaborn graphs directly into output directories.
• Export Agent: Autogenerate clean Excel workbooks, interactive HTML, or formatted PDF reports.
• Schema Agent: Automate rigorous data-type profiling and enforce structural constraints.
• ML Agent: Train and evaluate basic modeling pipelines (e.g., scikit-learn regressions or classification splits).

DS-STAR routes simple tasks (such as inspecting data headers or making routing choices) to the low-cost Claude Haiku model. It reserves complex operations (such as logic planning, code generation, and validation) for Sonnet or Opus.

You can analyze structured formats like CSV and JSON, as well as unstructured TXT documents.

It is a multi-agent framework built around the "Structured Thought and Action" architecture. It automates exploratory data analysis and Python execution directly in your local command-line environment.

Yes. The framework includes a specialized Debugger agent that captures console tracebacks, edits the failing script, and retries execution.

Yes. Because every step, prompt, generated script, and output log is saved in your local runs/ directory, every single execution is transparent and reproducible.

• 📖 Original Paper: DS-STAR: Domain Adaptive Data Science via Large Language Models
• 💾 Original Codebase: JulesLscx/DS-Star on GitHub
• 🐛 Report Issues: Skills Marketplace Issues
• 💬 Discussions: Skills Marketplace Discussions
• ⚙️ Underlying Architecture: Learn more at What are Skills? and How to Install.

View more Data Science & ML Skills

• openclaw Diagram Maker & Visualizer — Generates professional SVG, HTML, and Excalidraw diagrams for software architecture, system flows, and educational concepts.
• Pie Skills Constitution Consistency (Premium) — Verifies logic and thinking are aligned with the Anthropic constitution before responding.
• openclaw GH Issues Auto-Fixer — Automates the end-to-end GitHub issue lifecycle by spawning sub-agents to implement code fixes, open pull requests, and resolve review comments.

View all MCP Servers

• qdrant Qdrant — Connects language models to a Qdrant vector database for storing and retrieving information.
• datawiz168 Snowflake Integration — Enables Claude to execute SQL queries and interact with Snowflake databases.
• kablewy FRED — Accesses and retrieves economic data series from the Federal Reserve Economic Data (FRED) system.

• Multi-Agent Orchestration: By splitting tasks among seven specialized agent roles, DS-STAR handles planning, code generation, error correction, and validation in a structured, modular loop.
• Significant Cost Savings: Dynamically routes sub-tasks between Claude Haiku, Sonnet, and Opus, lowering total API consumption expenses by 50% to 60%.
• Automatic Debugging: Features an iterative self-correction routine that captures execution faults and rewrites Python code automatically to overcome runtime errors.
• 100% Reproducible: Saves every intermediate plan, code artifact, prompt template, and output response to local run folders (runs/<run_id>) for complete auditability.