microservices-patterns
Design microservices architectures with service boundaries, event-driven communication, and resilience patterns. Use when building distributed systems, decomposing monoliths, or implementing microservices.
80
54%
Does it follow best practices?
Impact
97%
1.42xAverage score across 6 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/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 covering 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 or distributed systems 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
27%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a comprehensive but overly verbose reference document that explains many microservices concepts Claude already knows. While the code examples demonstrate real patterns (Saga, Circuit Breaker, Event Bus), they aren't truly executable due to undefined types and missing infrastructure. The monolithic structure with no progressive disclosure and redundant concept explanations significantly reduces its effectiveness as a skill file.
Suggestions
Remove the 'Core Concepts' section entirely — it duplicates content expanded later and explains concepts Claude already knows (REST, gRPC, circuit breakers, etc.)
Make code examples executable by defining all referenced types (StepResult, SagaResult, Order, etc.) or use stdlib/well-known library types only
Split into multiple files: keep SKILL.md as a concise overview (~50 lines) pointing to COMMUNICATION.md, RESILIENCE.md, SAGA.md for detailed patterns
Add explicit validation/verification steps: how to test service boundaries, verify event delivery, validate circuit breaker behavior
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines. The 'Core Concepts' section repeats information that is then expanded in later sections. Bullet-point lists explaining what REST, gRPC, Kafka, etc. are is unnecessary for Claude. The entire 'When to Use This Skill' section and concept explanations like 'Database Per Service - Each service owns its data - No shared databases - Loose coupling' are things Claude already knows well. | 1 / 3 |
Actionability | Code examples are fairly concrete and illustrative (EventBus, CircuitBreaker, Saga pattern), but they are not truly executable — they reference undefined types (Order, PaymentRequest, StepResult, SagaResult, etc.), missing imports, and depend on unshown infrastructure. They serve more as detailed pseudocode/templates than copy-paste ready implementations. | 2 / 3 |
Workflow Clarity | The Saga pattern shows a clear multi-step process with compensation (error recovery), which is good. However, there are no explicit validation checkpoints, no verification steps after deploying or testing services, and no guidance on how to validate that the architecture is working correctly. The overall document reads more like a reference catalog than a guided workflow. | 2 / 3 |
Progressive Disclosure | Monolithic wall of content with no references to external files and no bundle files. All patterns are inlined in a single massive document. The 'Core Concepts' section duplicates what's expanded below. Content would benefit greatly from splitting into separate files (e.g., COMMUNICATION.md, RESILIENCE.md, SAGA.md) with the main file serving as an overview. | 1 / 3 |
Total | 6 / 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 (565 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- wshobson/agents
- Commit
112197c
- 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.