Add Claude Code skill for Burr by skrawcz · Pull Request #644 · apache/burr

skrawcz · 2026-01-31T19:02:15Z

Add Claude Code Plugin for Apache Burr

This PR adds an official Claude Code skill/plugin that provides expert AI assistance for building Burr applications.

Summary

Adds a comprehensive Claude Code plugin at .claude/plugins/burr/ that teaches Claude how to build stateful applications using Apache Burr. The plugin includes extensive documentation
covering APIs, patterns, examples, and troubleshooting.

What's Included

Plugin Structure:

.claude/plugins/burr/.claude-plugin/ - Plugin configuration and marketplace metadata
.claude/plugins/burr/skills/burr/ - Skill documentation and knowledge base
- SKILL.md - Main skill instructions and system prompt
- api-reference.md - Complete API documentation
- examples.md - Code examples and use cases
- patterns.md - Best practices and common patterns
- troubleshooting.md - Common issues and solutions

Documentation Updates:

Updated main README.md with Claude skill installation instructions
Added docs/getting_started/claude-skill.rst with comprehensive usage guide
Added plugin to documentation index

Installation

Users can install the skill in three ways:

From GitHub (easiest)

claude skill install https://github.com/apache/burr/.claude/plugins/burr

Manual personal install

cp -r /path/to/burr/.claude/plugins/burr ~/.claude/plugins/

Project-level install

cp -r /path/to/burr/.claude/plugins/burr .claude/plugins/

Usage

Once installed, users can activate the skill by:

Using /burr command in Claude Code
Asking Claude naturally: "Help me build a Burr application"

The skill provides expert guidance on:

State machine design and workflows
Writing actions with proper state management
Transition logic and graph structure
LLM integration and agentic workflows
Observability and debugging
Best practices and anti-patterns

Testing

To test the plugin:

Install it using one of the methods above
Run Claude Code and try /burr or ask about building a Burr application
Verify Claude provides Burr-specific guidance and follows best practices

Changes

adds skill
adds to docs

How I tested this

Notes

need to audit this a bit more still

Checklist

PR has an informative and human-readable title (this will be pulled into the release notes)
Changes are limited to a single goal (no scope creep)
Code passed the pre-commit check & code is left cleaner/nicer than when first encountered.
Any change in functionality is tested
New functions are documented (with a description, list of inputs, and expected output)
Placeholder code is flagged / future TODOs are captured in comments
Project documentation has been updated if adding/changing functionality.

This adds a comprehensive Claude Code skill that helps developers build applications with Apache Burr. When active in Claude Code, it provides: - Expert guidance on Burr APIs and patterns - Code generation for actions, state machines, and applications - Code review for best practices - Debugging assistance - Working examples for common patterns The skill includes: - SKILL.md: Main skill instructions for Claude - api-reference.md: Complete API documentation - examples.md: Working code examples - patterns.md: Best practices and design patterns - troubleshooting.md: Common issues and solutions - README.md: Installation and usage guide - plugin.json: Plugin manifest for easy installation Easy installation via Claude CLI: claude skill install https://github.com/apache/burr/.claude/skills/burr Or manual install by copying to ~/.claude/skills/burr/ for personal use or .claude/skills/burr/ for project-specific use. Documentation added at: - docs/getting_started/claude-skill.rst: Full usage guide - CLAUDE_SKILL.md: Quick start guide - Main README updated with installation instructions Contributions welcome via issues or pull requests!

github-actions · 2026-01-31T19:03:51Z

A preview of 2e90eaf is uploaded and can be seen here:

✨ https://burr.dagworks.io/pull/644 ✨

Changes may take a few minutes to propagate. Since this is a preview of production, content with draft: true will not be rendered. The source is here: https://github.com/apache/burr/tree/gh-pages/pull/644/

skrawcz · 2026-01-31T19:04:57Z

.claude/skills/burr/examples.md

+        # These three run in parallel
+        ("start", "analyze_sentiment"),
+        ("start", "extract_entities"),
+        ("start", "extract_keywords"),


this is incorrect...

.claude/plugins/burr/skills/burr/patterns.md

skrawcz · 2026-01-31T19:07:58Z

.claude/plugins/burr/skills/burr/patterns.md

+
+Given the same state and inputs, an action should always produce the same output.
+
+**❌ Bad - Non-deterministic:**


skrawcz · 2026-01-31T19:08:28Z

.claude/skills/burr/patterns.md

+    graph.GraphBuilder()
+    .with_actions(summarize, analyze_sentiment, extract_topics, create_report)
+    .with_transitions(
+        # Parallel execution


.claude/plugins/burr/skills/burr/SKILL.md

skrawcz · 2026-01-31T19:09:30Z

.claude/plugins/burr/skills/burr/SKILL.md

+
+1. **Type annotations**: Always use type hints for state and action parameters
+2. **Action purity**: Actions should be deterministic given the same state
+3. **State immutability**: Never mutate state directly, always use `.update()` or `.append()`


This commit corrects and improves the Claude Code skill documentation with three major fixes: 1. Fix parallelism documentation - Remove incorrect graph-based parallelism examples - Add correct MapStates, MapActions, MapActionsAndStates patterns - Include RunnableGraph for subgraph parallelism - Update examples in SKILL.md, examples.md, patterns.md, troubleshooting.md 2. Fix state management guidance - Correct action return pattern: Tuple[dict, State] - Show proper state access with bracket notation: state["key"] - Document state immutability and method chaining - Add comprehensive Pydantic typed state section - Contrast regular state vs Pydantic typed state patterns - Update all examples to show correct patterns 3. Use proper noun "Apache Burr" consistently - Update all skill files to use "Apache Burr" instead of just "Burr" - Maintain consistency across documentation Additional improvements: - Delete redundant CLAUDE_SKILL.md (consolidate with .claude/skills/burr/README.md) - Update README.md to point to correct skill location - Add complete state method documentation (update, append, extend, increment, etc.) - Add Pydantic typed state examples to examples.md

Restructures the Burr plugin from a flat skill structure to a nested marketplace-ready format that matches the Hamilton plugin organization. Changes: - Move from .claude/skills/burr/ to .claude/plugins/burr/ structure - Add .claude-plugin/ subdirectory with separated metadata: - plugin.json: References ./skills/ directory - marketplace.json: Marketplace distribution metadata - Add plugin-level documentation: - CHANGELOG.md: Version history and changes - README.md: Installation and usage guide - Nest skill content under skills/burr/ subdirectory - Remove embedded skill config from plugin.json This structure supports marketplace distribution, enables multiple skills per plugin, and follows Claude Code plugin best practices.

Adds detailed State Management Patterns section to patterns.md covering both regular dictionary-based state and Pydantic typed state patterns, bringing it in line with SKILL.md.

Removed sections on state immutability and deterministic actions from patterns.md.

Rearranged best practices for Apache Burr code to improve clarity.

Removed section on multi-source/target transitions from API reference.

skrawcz commented Jan 31, 2026

View reviewed changes

.claude/plugins/burr/skills/burr/patterns.md Outdated Show resolved Hide resolved

skrawcz commented Jan 31, 2026

View reviewed changes

.claude/plugins/burr/skills/burr/SKILL.md Show resolved Hide resolved

skrawcz commented Jan 31, 2026

View reviewed changes

skrawcz added 6 commits January 31, 2026 11:43

Add comprehensive state management patterns to skill documentation

b674da8

Adds detailed State Management Patterns section to patterns.md covering both regular dictionary-based state and Pydantic typed state patterns, bringing it in line with SKILL.md.

Remove state immutability and deterministic actions sections

13ccfc4

Removed sections on state immutability and deterministic actions from patterns.md.

Reorganize best practices in SKILL.md

92cb8ca

Rearranged best practices for Apache Burr code to improve clarity.

Delete multi-source/target transitions section

2e90eaf

Removed section on multi-source/target transitions from API reference.

skrawcz added the help wanted Contributors wanted! label Jan 31, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Claude Code skill for Burr#644

Add Claude Code skill for Burr#644
skrawcz wants to merge 7 commits intomainfrom
stefan/add-skills

skrawcz commented Jan 31, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Jan 31, 2026 •

edited

Loading

Uh oh!

skrawcz Jan 31, 2026

Uh oh!

Uh oh!

skrawcz Jan 31, 2026

Uh oh!

skrawcz Jan 31, 2026

Uh oh!

Uh oh!

skrawcz Jan 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		Given the same state and inputs, an action should always produce the same output.

		❌ Bad - Non-deterministic:

Conversation

skrawcz commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's Included

Plugin Structure:

Documentation Updates:

Installation

From GitHub (easiest)

Manual personal install

Project-level install

Usage

Testing

Changes

How I tested this

Notes

Checklist

Uh oh!

github-actions bot commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

skrawcz Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

skrawcz Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

skrawcz Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

skrawcz Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

skrawcz commented Jan 31, 2026 •

edited

Loading

github-actions bot commented Jan 31, 2026 •

edited

Loading