intertwine/dspy-agent-skills: Production DSPy Skills for Claude Code & Codex

intertwine/dspy-agent-skills: Production DSPy Skills for Claude Code & Codex

Building reliable LLM pipelines with DSPy requires more than understanding signatures and modules—it demands rigorous evaluation, systematic optimization, and reproducible workflows. Yet most developers still piece together DSPy code from scattered documentation, stale examples, and inferred APIs that broke three minor versions ago. The result: brittle programs, wasted API spend, and optimization runs that can't be replicated.

intertwine/dspy-agent-skills addresses this directly. It's a validated, spec-compliant pack of five agent skills that turns Claude Code, Codex CLI, and any agentskills.io-compatible agent into a DSPy 3.2.x expert—with committed benchmark artifacts, offline dry-run support, and progressive disclosure from quick-start to deep reference. This article walks through what the project delivers, how to install it, and where it fits in a modern LLM engineering stack.

What is intertwine/dspy-agent-skills?

intertwine/dspy-agent-skills is an open-source skill pack maintained by Bryan Young (@intertwine) with validation and spec-alignment work by Claude Opus 4.7. Released under the MIT License, the project targets DSPy 3.2.x (validated against 3.2.1) and provides five discrete agent skills packaged for both Claude Code and OpenAI's Codex CLI.

The repository sits at the intersection of three trends: the rise of agent-native development environments (where AI coding assistants execute skills rather than just suggest completions), the maturation of DSPy as a framework for programming—rather than prompting—language models, and the demand for reproducible optimization workflows that don't require re-reading documentation every minor version bump.

With 264 GitHub stars and 23 forks as of its last commit on 2026-06-20, it's a focused, utility-driven project rather than a broad ecosystem play. The emphasis is on validation: every API claim is grounded in official DSPy 3.2.x docs, every example ships with committed baseline vs. optimized numbers, and the test suite validates frontmatter spec compliance, JSON schema, Python^{↗ Bright Coding Blog} AST correctness, and version alignment. This isn't inferred knowledge—it's tested against the real API surface.

The dual-agent packaging is particularly notable. Rather than maintaining separate Claude and Codex skill sets, intertwine/dspy-agent-skills serves as a single source of truth, with a unified installer that symlinks into both ~/.claude/skills/ and ~/.agents/skills/.

Key Features

Five Progressive Agent Skills The skill pack decomposes DSPy expertise into five auto-invoking capabilities: dspy-fundamentals for signatures, modules, and save/load patterns; dspy-evaluation-harness for metrics and dev/val splitting; dspy-gepa-optimizer for program compilation with GEPA; dspy-rlm-module for long-context recursive exploration; and dspy-advanced-workflow as an orchestration layer that chains the other four.

Validated Against Live API, Not Stale Docs The project explicitly distinguishes itself from documentation-derived examples. The validation suite includes a script that checks the current DSPy API surface against what the skills assume, catching breaking changes before they reach users.

Progressive Disclosure Architecture Each skill ships with a concise SKILL.md for immediate use and a deep reference.md for extended study. This respects developer workflow: get the agent working now, dive deeper when needed.

Runnable Examples with Committed Artifacts Three end-to-end examples under examples/ exercise every skill against real language models. The repository includes committed baseline and GEPA-optimized scores with explicit version labels—no "trust me, it works" claims. Example 01 (RAG QA) shows a +19.53 point improvement; Example 02 (math reasoning) shows +8.33; Example 03 retains its historical DSPy 3.1.3 artifact for comparison integrity.

Offline Dry-Run Support Every example_*.py supports --dry-run execution without API keys. This enables CI integration, rapid iteration, and smoke testing in restricted environments.

Dual-Agent Marketplace Packaging The project provides both a Claude plugin manifest (.claude-plugin/) and marketplace manifest, plus compatibility with the Vercel skills CLI. One repository serves multiple agent ecosystems.

Use Cases

Rapid DSPy Onboarding for Agent-Native Teams Teams using Claude Code or Codex CLI as their primary development interface can onboard engineers to DSPy without context-switching to documentation. The agent auto-loads relevant skills based on task description—mention "optimize with GEPA" and the appropriate skill activates.

Reproducible Optimization Benchmarking The committed artifact pattern (baseline score, optimized score, Δ, DSPy version, LM used, date refreshed) provides a template for teams building internal benchmark suites. Example 01's clean comparison refreshed on 2026-04-28 demonstrates the discipline: exact commands, exact model versions, exact reproducibility notes.

CI/CD Pipeline Validation for DSPy Programs The --dry-run flag on all examples and the pytest validation suite enable pre-merge checks. Teams can verify that skill documentation matches code, that examples execute without runtime errors, and that version assumptions hold—all without API spend.

Multi-Agent Environment Standardization Organizations running both Claude Code and Codex CLI can maintain one skill repository rather than diverging forks. The ./scripts/install.sh installer handles per-agent targeting with --claude-only and --codex-only flags.

Long-Context Codebase QA with RLM The dspy-rlm-module skill specifically addresses recursive language model exploration for large codebases, with Pyodide sandbox support via Deno for isolated execution.

Installation & Setup

Claude Code (via marketplace)

/plugin marketplace add intertwine/dspy-agent-skills
/plugin install dspy-agent-skills@dspy-agent-skills

These commands register the plugin with Claude Code's marketplace system and install the skill pack. The @dspy-agent-skills suffix specifies the package identifier within the marketplace namespace.

Agent Skills CLI (Vercel skills)

npx skills add intertwine/dspy-agent-skills --list
npx skills add intertwine/dspy-agent-skills --skill '*' -a codex -y

Critical note: The Vercel skills CLI expects a GitHub owner/repo format, URL, well-known HTTPS endpoint, or local path. The bare form npx skills add dspy-agent-skills will fail unless upstream adds a source alias. Always use intertwine/dspy-agent-skills.

The --list flag previews available skills; --skill '*' installs all skills, -a codex targets the Codex agent, and -y auto-accepts prompts.

Claude Code + Codex (repo checkout)

git clone https://github.com/intertwine/dspy-agent-skills
cd dspy-agent-skills
./scripts/install.sh           # symlinks into ~/.claude/skills/ and ~/.agents/skills/

The installer defaults to symlinking for live updates. Key flags:

• --claude-only or --codex-only: single-agent installation
• --copy: copy files instead of symlink (for immutable deployments)
• --uninstall: remove existing symlinks/copies
• --dry-run: preview actions without executing

Manual Installation

Drop skills/* directories into ~/.claude/skills/ (Claude Code) or ~/.agents/skills/ (Codex CLI). See docs/installation.md for platform-specific paths and edge cases.

Validation

# Run full validation suite
uv run --with pytest python -m pytest tests/ -v

# Smoke-test every example offline (no API key needed)
for f in skills/*/example_*.py; do uv run --with dspy python "$f" --dry-run; done

Real Code Examples

The repository emphasizes runnable, committed artifacts over hypothetical snippets. Here are the key patterns developers will encounter:

Five-Second Demo Invocation

Rather than a code snippet, the project's core interaction model is natural language directed at the agent:

"Build a DSPy sentiment classifier, optimize it with GEPA, and save the artifact."

The agent auto-loads dspy-advanced-workflow, which chains through dspy-fundamentals (build the classifier), dspy-gepa-optimizer (compile with GEPA), and save/load patterns. No manual skill selection required—the orchestration skill handles dispatch.

Example Validation Loop (Offline)

# Iterate all skills with zero API spend
for f in skills/*/example_*.py; do 
    uv run --with dspy python "$f" --dry-run
done

This pattern enables CI integration: validate that all examples execute without runtime errors before any code merge. The --dry-run flag mocks LM calls, testing the DSPy program structure independently of model availability or API quotas.

Live GEPA Execution

cd skills/dspy-advanced-workflow
OPENAI_API_KEY=... uv run --with dspy python example_pipeline.py --auto light

The --auto light flag selects a lightweight optimization budget. This is the pattern for actual optimization runs: navigate to the skill directory, provide the API key via environment variable, and execute through uv for dependency isolation.

Version Pinning Verification

env -u UV_EXCLUDE_NEWER uv run --with dspy==3.2.1 python -c 'import dspy; print(dspy.__version__)'

This command explicitly unsets UV_EXCLUDE_NEWER (which can hide recent releases) and pins to the validated DSPy version. The repository includes this as a diagnostic: if uv run --with dspy resolves older than 3.2.1, check for stale mirrors or environment variables.

Advanced Usage & Best Practices

Treat Committed Artifacts as Baseline Templates The three examples include explicit version labels and model identifiers. When adapting for your own benchmarks, maintain the same discipline: record DSPy version, LM identifier, date, and exact command. The repository's decision to retain Example 03's historical DSPy 3.1.3 artifact—even when 3.2.0 shows better numbers—demonstrates integrity over vanity metrics.

Use --dry-run for Agent Skill Development When extending or modifying skills, the offline execution path validates Python AST correctness and program structure without API costs. The validation suite (tests/) additionally checks frontmatter spec compliance and JSON schema—run this before submitting PRs or deploying to teams.

Prefer Symlinks for Active Development, Copies for Production The installer's default symlink enables git pull to update skills immediately. For reproducible deployments—where you want to pin a specific commit—use --copy and version-control the installed snapshot separately.

Monitor UV_EXCLUDE_NEWER in CI The repository explicitly flags this uv environment variable as a source of stale dependency resolution. In CI pipelines, ensure it's unset or explicitly overridden when validating against current DSPy releases.

Comparison with Alternatives

The raw DSPy documentation remains essential for deep framework understanding—intertwine/dspy-agent-skills doesn't replace it but operationalizes it for agent-assisted development. Custom wikis offer organizational specificity but carry maintenance burden and version drift risk. This skill pack occupies a middle ground: opinionated enough to accelerate work, validated enough to trust, and open enough to inspect and modify.

FAQ

What DSPy versions are supported? DSPy 3.2.x, tested against 3.2.1. Committed example artifacts retain their original version labels for comparison integrity.

Do I need API keys for installation or validation? No. Installation requires only Git and shell access. The validation suite and all --dry-run example executions work offline.

Can I use only Claude Code or only Codex CLI? Yes. The ./scripts/install.sh accepts --claude-only and --codex-only flags. Manual installation also allows selective placement.

What's the license? MIT License. Commercial use, modification, and redistribution permitted with attribution.

Why does Example 03 use DSPy 3.1.3? The historical artifact is retained because a clean 3.2.0 baseline on comparable models already reached 0.944, leaving insufficient headroom for a meaningful GEPA comparison. This preserves honest benchmarking over forced updates.

What's required for dspy.RLM examples? Deno runtime, for Pyodide sandbox execution. Not needed for the other four skills.

How do I report API mismatches? The repository includes scripts/check_dspy_surface.py for validation. Run with env -u UV_EXCLUDE_NEWER uv run --with dspy==3.2.1 python scripts/check_dspy_surface.py and file issues with output.

Conclusion

intertwine/dspy-agent-skills is a disciplined, utility-focused project for teams already committed to DSPy and agent-native development workflows. It won't teach you DSPy from scratch—that's still the documentation's role—but it will make your Claude Code or Codex CLI instance reliably productive with DSPy 3.2.x, with validation infrastructure that catches drift before it wastes API budget.

The committed artifacts, offline dry-run support, and explicit version pinning demonstrate maintenance maturity rare in open-source tooling. For ML engineers, backend developers, and DevOps^{↗ Bright Coding Blog} teams building reproducible LLM pipelines, this skill pack reduces friction without hiding complexity.

Explore the repository, run the validation suite, and test the five-second demo in your agent: https://github.com/intertwine/dspy-agent-skills. For teams standardizing across multiple agent platforms, the single-source-of-truth architecture alone may justify adoption.

[INTERNAL_LINK: DSPy framework introduction for Python developers]