microservices-patterns
Design microservices architectures with service boundaries, event-driven communication, and resilience patterns. Use when building distributed systems, decomposing monoliths, or implementing microservices.
72
58%
Does it follow best practices?
Impact
98%
1.81xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-wshobson/backend-development/skills/microservices-patterns/SKILL.mdQuality
Discovery
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid description that clearly communicates both what the skill does and when to use it, with good trigger terms from the microservices domain. Its main weaknesses are that the capabilities listed are somewhat conceptual rather than concrete discrete actions, and there is moderate overlap risk with adjacent architecture-related skills.
Suggestions
Make capabilities more concrete by listing specific deliverables, e.g., 'Define service boundaries, design API contracts, create event schemas, implement circuit breakers and retry policies'.
Add more distinctive trigger terms or narrow the scope to reduce overlap with general architecture skills, e.g., mention specific patterns like 'saga pattern', 'CQRS', 'API gateway', or specific file types/diagrams produced.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (microservices) and some actions ('design architectures', 'service boundaries', 'event-driven communication', 'resilience patterns'), but these are more like architectural concepts than concrete discrete actions. Compare to the level 3 example which lists very specific operations like 'extract text', 'fill forms', 'merge documents'. | 2 / 3 |
Completeness | Clearly answers both 'what' (design microservices architectures with service boundaries, event-driven communication, and resilience patterns) and 'when' (use when building distributed systems, decomposing monoliths, or implementing microservices) with an explicit 'Use when...' clause. | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'microservices', 'distributed systems', 'decomposing monoliths', 'service boundaries', 'event-driven', 'resilience patterns'. These cover the main terms a user working in this domain would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | While 'microservices' is a fairly specific domain, terms like 'distributed systems' and 'resilience patterns' could overlap with skills focused on general system design, cloud architecture, or infrastructure. The description could conflict with a broader software architecture skill. | 2 / 3 |
Total | 10 / 12 Passed |
Implementation
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill reads like a textbook chapter on microservices patterns rather than a targeted skill for Claude. It is excessively verbose, explaining well-known concepts (circuit breakers, sagas, event-driven architecture) that Claude already understands deeply. The code examples, while structured, are not truly executable due to undefined types and missing imports, and the referenced bundle files don't exist.
Suggestions
Reduce content by 60-70%: remove all conceptual explanations Claude already knows (what circuit breakers are, what sagas are, etc.) and focus only on project-specific conventions, preferred libraries, and concrete implementation decisions.
Make code examples truly executable by defining all referenced types (StepResult, SagaResult, Order, etc.) or use simpler self-contained examples that can actually run.
Either provide the referenced bundle files (references/service-decomposition-guide.md, assets/circuit-breaker.py, etc.) or remove the references section. Move the lengthy code examples into those bundle files and keep SKILL.md as a concise overview.
Add a concrete workflow with validation steps for the actual task of decomposing a monolith or designing service boundaries, rather than just listing patterns.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. Explains concepts Claude already knows well (what REST is, what circuit breakers are, what sagas are). The bullet-point concept summaries ('Fail fast on repeated errors', 'Prevent cascade failures') add no value. The code examples, while illustrative, are lengthy pseudo-implementations that restate textbook patterns rather than providing novel, project-specific guidance. | 1 / 3 |
Actionability | Code examples are fairly concrete and demonstrate real patterns with real libraries (aiokafka, httpx, tenacity, FastAPI), but they rely on undefined types (Order, StepResult, SagaResult, PaymentRequest, etc.) making them not truly executable. They are closer to detailed pseudocode than copy-paste ready implementations. | 2 / 3 |
Workflow Clarity | The Saga pattern shows a clear multi-step sequence with compensation logic, which is good. However, there's no explicit validation or verification workflow for the overall process of designing/implementing microservices. No checklist for verifying service boundaries, no validation steps for testing communication patterns, and no feedback loops for iterating on the architecture. | 2 / 3 |
Progressive Disclosure | References to external files (references/service-decomposition-guide.md, assets/circuit-breaker.py, etc.) are listed but no bundle files exist, so these are phantom references. The main content is a monolithic wall of code examples that could benefit from being split out, with the SKILL.md serving as a concise overview pointing to detailed implementations. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (596 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- Dicklesworthstone/pi_agent_rust
- Commit
99da384
- Reviewed
Table of Contents
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.