dspy-agent-skills: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (or any agent) working inside this repo.

What this repo is

A pack of agent skills that teaches coding agents to build, optimize, and ship DSPy 3.2.x programs. It is designed to install cleanly into both Claude Code (~/.claude/skills/) and Codex CLI (~/.agents/skills/).

The skills themselves are in skills/<name>/SKILL.md. The product is Markdown; Python files in skills/*/example_*.py are runnable smoke tests, not library code.

Commands you'll actually run

# Validate all skill metadata, manifests, example syntax, and skill-doc correctness
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

# Validate the live DSPy API surface taught by these skills
env -u UV_EXCLUDE_NEWER uv run --with dspy==3.2.1 python scripts/check_dspy_surface.py

# Install skills locally into Claude Code and Codex (symlinks, idempotent)
./scripts/install.sh

# Uninstall
./scripts/install.sh --uninstall

# Live GEPA run (requires OPENAI_API_KEY)
cd skills/dspy-advanced-workflow
OPENAI_API_KEY=... uv run --with dspy python example_pipeline.py --auto light

If uv run --with dspy unexpectedly resolves an older DSPy release, check for UV_EXCLUDE_NEWER or another resolver policy that hides recent uploads. For an exact DSPy 3.2.1 validation run, use:

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

Authoring / editing conventions

SKILL.md frontmatter — spec-only fields

Claude Code and Codex both follow the agentskills.io spec. Only these fields are honored in SKILL.md frontmatter:

• name (required, kebab-case, ≤64 chars, must equal the parent directory name)
• description (required; combined with when_to_use must stay ≤1536 chars)
• when_to_use, argument-hint, disable-model-invocation, user-invocable, allowed-tools, model, effort, context, agent, hooks, paths, shell