# AGENTS.md This repository contains skill definitions for building Dapr Workflow applications and durable AI agent applications that run on Dapr Workflow. The skills follow the [Agent Skills specification](https://agentskills.io/home) and can be used with any compatible AI coding assistant. ## Repository structure - `skills/` — Skill files organized by language/framework - `dapr-shared/` — Support skill holding shared content referenced by multiple skills (prereq checks, component YAMLs, tool templates, observability, running instructions). It has its own `SKILL.md` so it installs next to the other skills. ### Workflow skills - `check-prereq-dotnet/SKILL.md` — Skill for checking .NET prerequisites - `check-prereq-aspire/SKILL.md` — Skill for checking .NET Aspire prerequisites - `check-prereq-python/SKILL.md` — Skill for checking Python prerequisites - `create-workflow-dotnet/SKILL.md` — Skill for creating Dapr Workflow apps with .NET - `create-workflow-dotnet/REFERENCE.md` — Detailed reference examples for the .NET skill - `create-workflow-python/SKILL.md` — Skill for creating Dapr Workflow apps with Python - `create-workflow-python/REFERENCE.md` — Detailed reference examples for the Python skill - `create-workflow-typescript/SKILL.md` — Skill for creating a Dapr building-blocks app (Workflow, service invocation, pub/sub, bindings, jobs, state, secrets) with TypeScript - `create-workflow-typescript/REFERENCE.md` — Detailed reference examples for the TypeScript skill - `migrate-workflow-typescript/SKILL.md` — Skill for migrating an existing TypeScript/Node.js application to Dapr incrementally - `migrate-workflow-typescript/REFERENCE.md` — Detection heuristics, infra-to-component mapping, and verified before/after code for the migration skill - `add-workflow-dotnet/SKILL.md` — Skill for adding Dapr Workflow to an existing ASP.NET Core project (plain or Aspire) after a plan the user approves - `add-workflow-dotnet/REFERENCE.md` — Detection heuristics, plan template, edit recipes and run-doc template for the add skill - `create-workflow-aspire/SKILL.md` — Skill for creating Dapr Workflow apps with Aspire - `create-workflow-aspire/REFERENCE.md` — Detailed reference examples for the Aspire skill - `create-workflow-from-diagram/SKILL.md` — Skill for scaffolding a Dapr Workflow app from a diagram image (PNG/JPG/GIF/WebP) or a BPMN 2.0 XML file, in Go, Python, .NET, Java, or JavaScript - `create-workflow-from-diagram/REFERENCE.md` — Detailed reference for the diagram skill (IR, input paths, per-language notes) - `review-workflow-determinism/SKILL.md` — Skill for reviewing existing workflow code for non-determinism hazards - `review-workflow-determinism/REFERENCE.md` — Detailed reference and worked example for the determinism review skill - `review-workflow-activity/SKILL.md` — Skill for reviewing existing activity code for idempotency, error handling, and convention issues - `review-workflow-activity/REFERENCE.md` — Detailed reference and worked example for the activity review skill - `review-workflow-management/SKILL.md` — Skill for reviewing the HTTP management endpoints exposed for Dapr Workflows - `review-workflow-management/REFERENCE.md` — Detailed reference and worked example for the management endpoint review skill ### Agent skills - `check-prereq-agent-python/SKILL.md` — Prerequisites for Python agents (`dapr-agents` SDK or a `diagrid` framework wrapper) - `check-prereq-agent-dotnet/SKILL.md` — Prerequisites for .NET agents (Microsoft Agent Framework on Dapr Workflow) - `create-agent-python/SKILL.md` — Skill for creating durable agent apps in Python - `create-agent-python/REFERENCE.md` — Detailed reference examples for the Python agent skill - `create-agent-dotnet/SKILL.md` — Skill for creating durable agent apps in .NET - `create-agent-dotnet/REFERENCE.md` — Detailed reference examples for the .NET agent skill - `review-agent-tools/SKILL.md` — Skill for reviewing agent tool definitions (idempotency, descriptions, payload size, exception handling) - `review-agent-tools/REFERENCE.md` — Detailed reference and worked example for the tool review skill - `review-agent-memory/SKILL.md` — Skill for reviewing agent memory and state-store configuration - `review-agent-memory/REFERENCE.md` — Detailed reference and worked example for the memory review skill - `review-agent-orchestration/SKILL.md` — Skill for reviewing multi-agent pub/sub conventions, loop safety, and port assignment - `review-agent-orchestration/REFERENCE.md` — Detailed reference and worked example for the orchestration review skill - `review-agent-observability/SKILL.md` — Skill for reviewing agent tracing, metrics, and structured logging - `review-agent-observability/REFERENCE.md` — Detailed reference and worked example for the observability review skill ## Usage **Verify your environment (user-invoked only):** The `check-prereq-xxx` skills (`check-prereq-dotnet`, `check-prereq-aspire`, `check-prereq-python`, `check-prereq-agent-python`, `check-prereq-agent-dotnet`) are opt-in and must **only** be run when the user explicitly asks for them (e.g., "check prerequisites for .NET", "verify Aspire environment"). Do **NOT** run them automatically as part of, or before, a `create-workflow-xxx` or `create-agent-xxx` invocation — they are separate, user-invoked skills, not an implicit pre-step. **Build a new workflow application:** Run the appropriate `create-workflow-xxx` skill to scaffold the project: `create-workflow-dotnet`, `create-workflow-aspire`, `create-workflow-python`, or `create-workflow-typescript` from a text spec, or `create-workflow-from-diagram` from an image or BPMN file (output language: Go, Python, .NET, Java, or JavaScript). `create-workflow-typescript` differs from the other three: it scaffolds a Workflow whose activities also exercise service invocation, pub/sub, bindings, jobs, state, and secrets, rather than a workflow-only app. Each skill lists the prerequisites it expects to be installed and assumes they are already in place. **Migrate an existing application to Dapr:** Run `migrate-workflow-typescript` on an existing TypeScript/Node.js application — it is not a scaffolder. It reads the codebase first (no changes), maps existing service calls, messaging, scheduled jobs, secrets, and state access onto Dapr building blocks, presents a Migration Assessment Report for approval, and only then applies confirmed changes one integration point at a time, verifying after each with the project's own build/test commands. It works on a dedicated git branch and never commits or pushes unless the user opts into per-step commits. This is a fundamentally different kind of skill from the `create-workflow-xxx` family: it never assumes a fixed scenario and never rewrites whole files. **Add Dapr Workflow to an existing .NET project:** Run `add-workflow-dotnet` on an existing ASP.NET Core project (net8.0, net9.0 or net10.0, optionally inside an Aspire solution). It inspects the solution, shows an Add Workflow Plan for approval, then adds `Dapr.Workflow`, the Dapr wiring, the workflow and its activities, and the management endpoints with targeted edits, building after each step and running the existing tests at the end. It never changes git state and writes a `DAPR-WORKFLOW.md` instead of editing the README. **Build a new agent application:** Run `create-agent-python` or `create-agent-dotnet` to scaffold a durable agent app. `create-agent-python` covers the native [`dapr-agents`](https://github.com/dapr/dapr-agents) SDK and the [`diagrid`](https://pypi.org/project/diagrid/) framework wrappers; `create-agent-dotnet` covers [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/) running on Dapr Workflow via [`Diagrid.AI.Microsoft.AgentFramework`](https://www.nuget.org/packages/Diagrid.AI.Microsoft.AgentFramework). Both support a single agent and a coordinator + specialists topology. **Review an existing workflow application** (run any combination, in any order): - `review-workflow-determinism` — flags non-deterministic constructs in workflow bodies that would break replay. - `review-workflow-activity` — flags idempotency, error-handling, and convention issues inside activities. - `review-workflow-management` — checks the HTTP management surface (start, status, terminate, pause, resume, raise-event, purge) against the canonical shape used by the `create-workflow-*` skills. **Review an existing agent application** (run any combination, in any order): - `review-agent-tools` — flags idempotency, description quality, unbounded returns, and swallowed exceptions in tool functions. - `review-agent-memory` — checks `actorStateStore: "true"` on the workflow store, memory-class appropriateness, and secret handling for LLM API keys. - `review-agent-orchestration` — checks multi-agent pub/sub topic conventions, loop bounds, agent-registry wiring, and port collisions. - `review-agent-observability` — checks tracing configuration, sampling rate, structured logging, and trace propagation on outbound calls. All review skills are read-only and emit a structured report with stable rule ids: `DWF-DET-NNN`, `DWF-ACT-NNN`, `DWF-MGT-NNN` for workflow reviews; `DAG-TOOL-NNN`, `DAG-MEM-NNN`, `DAG-ORCH-NNN`, `DAG-OBS-NNN` for agent reviews. ## Repository prerequisites All skills require: - [Docker](https://www.docker.com/products/docker-desktop/) or [Podman](https://podman.io/docs/installation) - [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/) (version 1.18+) - Optional: [Diagrid Dapr Dev Dashboard](https://github.com/diagridio/dev-dashboard) to inspect workflow runs, sidecars, components and logs locally. The `create-*` skills check whether it is installed (`diagrid-dev-dashboard --version`) without ever stopping, and end with a tip to install or start it. ### .NET skills - [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download) - C# language server support (for code diagnostics) ### .NET Aspire skills - [.NET 10 SDK](https://dotnet.microsoft.com/en-us/download) - [Aspire CLI](https://aspire.dev/get-started/install-cli/) - C# language server support (for code diagnostics) ### Python skills - Python 3.12+ for workflow skills, Python 3.11–3.13 for agent skills — [download Python](https://www.python.org/downloads/) - [uv](https://docs.astral.sh/uv/getting-started/installation/) - Python language server support (for code diagnostics) ### TypeScript skills - Node.js 22+ (LTS) — [download Node.js](https://nodejs.org/en/download) - TypeScript language server support (for code diagnostics) ### Agent skills (both languages) - At least one LLM provider: an `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` or `GOOGLE_API_KEY` environment variable, or a local [Ollama](https://ollama.com/) instance on `http://localhost:11434`. - Python agent projects accept Python 3.11–3.13 (the `diagrid` distribution requires `>=3.11,<3.14`). ## Guidelines for skill files - Skill files are Markdown documents in `skills//SKILL.md` - Each skill directory should also include a `REFERENCE.md` with full code examples and detailed explanations - Skill front-matter fields: `name`, `description` - Each skill should include sections for: prerequisite checks, project setup, folder structure, verify, and a final message - Use `` syntax for values the user should replace (e.g., ``, ``) - Code examples should be complete and runnable, not snippets - The SKILL.md file should be minimal; detailed code examples belong in `REFERENCE.md` - Include "Key points" sections after code examples to explain important concepts - Skills must perform all prerequisite checks before creating any files - Skills must be able to work on MacOS, Linux, and Windows environments. - Shared content goes in `skills/dapr-shared/`; SKILL.md and REFERENCE.md files reference it as `../dapr-shared/` to avoid duplication. Do not reference files outside the `skills/` folder from skill files — installers copy only the `skills//` folders. - Every folder under `skills/` must contain a `SKILL.md` whose `name` equals the folder name and that has a `description`. - Run `node scripts/validate-skills.mjs` (and `node --test "scripts/test/*.test.mjs"` when changing the scripts) before committing skill changes; CI runs both. ## Supported tools These skills follow the [Agent Skills specification](https://agentskills.io/home) and are compatible with AI coding assistants that support it, including: - [Claude Code](https://claude.com/product/claude-code) - [OpenAI Codex](https://openai.com/index/introducing-codex/) - [GitHub Copilot](https://github.com/features/copilot) - [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) - [Cursor](https://www.cursor.com/) - [Windsurf](https://windsurf.com/)