saga-orchestration

Patterns for managing distributed transactions and long-running business processes.

Quality

43%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/saga-orchestration/SKILL.md

Quality

Content

50%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This skill provides substantial, concrete saga orchestration templates with good coverage of orchestration, choreography, timeouts, and compensation patterns. However, it is excessively verbose for Claude's context window — Claude already understands saga patterns and could generate most of this code from brief specifications. The instructions section is too vague to be useful, and the referenced implementation-playbook.md doesn't exist in the bundle.

Suggestions

Drastically reduce the code templates to key structural patterns and decision points Claude wouldn't know (e.g., compensation ordering edge cases, idempotency key strategies) rather than full class implementations Claude can generate.

Replace the vague Instructions section ('Apply relevant best practices and validate outcomes') with a concrete workflow: e.g., 1) Identify saga boundaries, 2) Define steps with compensations, 3) Choose orchestration vs choreography based on criteria X, 4) Validate compensation coverage.

Move the full code templates into the referenced `resources/implementation-playbook.md` file and keep only a concise orchestrator skeleton in SKILL.md.

Add explicit validation/verification steps: how to test compensations, how to verify idempotency, how to simulate partial failures.

Dimension	Reasoning	Score
Conciseness	The skill is significantly verbose at ~350+ lines of code templates. Much of this is boilerplate Python that Claude could generate from a brief description. The saga state table, ASCII diagrams, and extensive code templates explain patterns Claude already understands well. The 'Do not use this skill when' and 'Use this skill when' sections add little value in the body content.	2 / 5
Actionability	The code templates are concrete, executable Python with clear class hierarchies, async methods, and realistic examples like order fulfillment. However, they are templates/patterns rather than copy-paste-ready solutions for a specific task — there's no saga_store or event_publisher implementation, so they can't run standalone. The guidance is concrete but has integration gaps.	4 / 5
Workflow Clarity	The saga execution states and step sequences are well-defined within the code itself (start → execute steps → handle completion/failure → compensate). However, there are no explicit validation checkpoints or verification steps for the developer implementing these patterns. The instructions section is extremely vague ('Apply relevant best practices and validate outcomes') with no concrete workflow for how to actually build and test a saga implementation.	3 / 5
Progressive Disclosure	The skill references `resources/implementation-playbook.md` for detailed examples, which is good progressive disclosure, but no bundle files exist to support this reference. The bulk of the content (4 large code templates) is inlined when it could be split into separate files. The structure has sections but the massive code blocks dominate and would benefit from being in referenced files.	3 / 5
	Total	12 / 20 Passed

Description

36%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is too vague and abstract—it names a domain but fails to list concrete actions or provide any 'when to use' guidance. It reads more like a topic heading than a skill description, lacking the specificity and trigger terms needed for reliable skill selection among many options.

Suggestions

Add concrete actions the skill performs, e.g., 'Implements saga patterns, designs compensation logic, orchestrates multi-service workflows, handles distributed rollbacks.'

Add an explicit 'Use when...' clause with trigger phrases, e.g., 'Use when the user asks about saga patterns, distributed transactions, event choreography, or coordinating multi-step business processes across microservices.'

Include natural synonyms and related terms users might mention, such as 'saga', 'orchestration', 'choreography', 'two-phase commit', 'compensating transactions', 'workflow engine'.

Dimension	Reasoning	Score
Specificity	Names the domain ('distributed transactions', 'long-running business processes') but provides no concrete actions—only says 'patterns for managing', which is vague and does not describe what the skill actually does.	2 / 5
Completeness	Provides a vague 'what' (patterns for managing) but has no 'when' clause at all. There is no explicit guidance on when Claude should select this skill, which caps this dimension at 3 per the rubric, and the weak 'what' brings it down further.	2 / 5
Trigger Term Quality	Includes some relevant keywords like 'distributed transactions' and 'long-running business processes', but misses natural synonyms and related terms users might say such as 'saga pattern', 'orchestration', 'compensation', 'workflow', 'event sourcing', or 'two-phase commit'.	3 / 5
Distinctiveness Conflict Risk	Somewhat specific to distributed transactions and business processes, but 'patterns for managing' is broad enough to overlap with general architecture skills, workflow skills, or microservices design skills.	3 / 5
	Total	10 / 20 Passed

Validation

81%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 9 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (508 lines); consider splitting into references/ and linking	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	9 / 11 Passed

Repository: administrakt0r/AI-Agents-Safe-Coding-Skills
Path: skills/saga-orchestration/SKILL.md
Commit: 57c135b

Reviewed: 2 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.