jbvc/software-architecture
Guide for quality focused software architecture. This skill should be used when users want to write code, design architecture, analyze code, in any case that relates to software development.
50
50%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
32%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 description is far too broad and generic to serve as a useful skill selector. It essentially claims ownership of all software development tasks, which makes it indistinguishable from any other coding-related skill. The 'quality focused' framing in the first sentence is never elaborated with specific practices or methodologies.
Suggestions
Narrow the scope significantly — specify what kind of architecture guidance (e.g., 'Guides design of microservices, API boundaries, database schemas, and system decomposition') rather than claiming all of software development.
Add distinct trigger terms that differentiate this from general coding skills, such as 'design patterns', 'SOLID principles', 'system design', 'scalability', 'technical debt', 'refactoring architecture'.
Replace the overly broad 'when' clause with specific scenarios, e.g., 'Use when the user asks about system design decisions, architectural trade-offs, code quality patterns, or needs a code review focused on maintainability and structure.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description says 'write code, design architecture, analyze code' which are extremely broad and vague actions. There are no concrete, specific capabilities listed — it reads more like a category label than a skill description. | 1 / 3 |
Completeness | It has a weak 'what' ('quality focused software architecture') and a 'when' clause ('when users want to write code, design architecture, analyze code, in any case that relates to software development'), but the 'when' is so broad it's essentially 'use for anything software-related', which provides no meaningful selection guidance. | 2 / 3 |
Trigger Term Quality | It includes some natural terms like 'write code', 'design architecture', 'analyze code', and 'software development', but these are overly broad and would match virtually any programming-related request. Missing specific variations or narrower trigger terms. | 2 / 3 |
Distinctiveness Conflict Risk | This description would conflict with virtually any coding, development, or engineering skill. 'Any case that relates to software development' is maximally generic and would trigger for nearly every programming-related request. | 1 / 3 |
Total | 6 / 12 Passed |
Implementation
37%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides a reasonable set of software architecture principles and coding guidelines, with some useful concrete examples like specific library recommendations and naming anti-patterns. However, it lacks executable code examples, any workflow or decision-making process, and has notable redundancy between the best practices and anti-patterns sections. The content reads more like a style guide checklist than an actionable skill that teaches Claude how to approach architecture decisions step by step.
Suggestions
Add a clear decision workflow for architecture choices, e.g., a step-by-step process: 1) Identify the domain problem, 2) Search for existing libraries/services, 3) Evaluate fit, 4) If custom code needed, apply DDD patterns, 5) Validate separation of concerns.
Include concrete, executable code examples showing good vs. bad architecture patterns (e.g., a before/after refactoring of a controller with mixed concerns into clean architecture layers).
Remove the anti-patterns section's duplication of rules already stated in best practices — consolidate into a single section with do/don't pairs for each principle.
Consider splitting into a concise SKILL.md overview with references to detailed files like NAMING_CONVENTIONS.md, LIBRARY_EVALUATION.md, and DDD_PATTERNS.md for deeper guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content has some redundancy — for example, the anti-patterns section largely restates rules already given in the best practices section (e.g., separation of concerns, generic naming). Some points like 'avoid code duplication' and 'proper error handling' are things Claude already knows. However, the domain-specific guidance (library-first approach, specific library examples) adds value. | 2 / 3 |
Actionability | The skill provides specific naming examples and concrete anti-patterns (e.g., 'use cockatiel instead of writing your own retry logic', 'don't build custom auth when Auth0/Supabase exists'), which is helpful. However, there are no executable code examples, no architecture templates, and no concrete implementation patterns — it remains largely at the level of principles and guidelines rather than copy-paste-ready guidance. | 2 / 3 |
Workflow Clarity | There is no clear workflow or sequenced process for how to approach software architecture decisions. The content is a flat list of rules and principles without any decision flowchart, step-by-step process, or validation checkpoints for architectural choices. | 1 / 3 |
Progressive Disclosure | The content is organized with headers and sub-sections, which provides some structure. However, it's a single monolithic file with no references to external resources or deeper documentation. For a broad topic like software architecture, splitting detailed guidance (e.g., DDD patterns, library evaluation criteria) into separate referenced files would improve navigation. | 2 / 3 |
Total | 7 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
Reviewed
Table of Contents