software-evaluation skill
✓ VerifiedEvaluates code quality across architecture, reliability, observability, security, and developer experience to produce a scorecard and improvement roadmap.
- GitHub stars
- 7
- Files
- 1
- Last commit
- Nov 7, 2026
- License
- MIT
- Allowed tools
- —
What does the software-evaluation skill do?
software-evaluation evaluates code quality across architecture, reliability, observability, security, and developer experience to produce a scorecard and improvement roadmap.
Summary generated from the skill's SKILL.md.
About the software-evaluation skill
Performing deep technical audits of codebases is what this skill enables for CTOs, architects, and principal engineers. It conducts rigorous, evidence-based reviews of a directory or module by analyzing the language, framework, and deployment target to ensure best practices are applied appropriately to the specific context. The tool evaluates software quality across five specific pillars: architectural integrity, reliability and resiliency, observability and operability, design-level security posture, and developer experience.
When an agent loads this skill, it performs a reconnaissance phase by scanning dependency files, entry points, core business logic, and error handling paths. It produces a detailed Markdown report containing a 1-10 scorecard with specific file and line citations for every claim, alongside a strategic improvement roadmap prioritized by business impact and engineering effort. The output includes a machine-readable JSON summary for dashboard integration and identifies P0 blockers that must be resolved before production deployment.
What an agent can do with it
- 1Conduct a comprehensive code auditRequest a full quality assessment of a specific directory from the perspective of a CTO or architect.
- 2Identify production deployment blockersFind critical security or reliability issues that prevent a codebase from being safely deployed.
- 3Evaluate architectural integrityAnalyze if a module follows single responsibility principles and maintains a clean dependency graph.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the software-evaluation skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the software-evaluation skill in Plugin
/plugin marketplace add northraystudio/maruda /plugin install maruda@northraystudio
Install the software-evaluation skill in Claude Code
~/.claude/skills/software-evaluation/SKILL.md
$ npx degit northraystudio/maruda/skills/software-evaluation ~/.claude/skills/software-evaluationInstall the software-evaluation skill in Claude Code (project)
.claude/skills/software-evaluation/SKILL.md
$ npx degit northraystudio/maruda/skills/software-evaluation .claude/skills/software-evaluationInstall the software-evaluation skill in Codex
~/.agents/skills/software-evaluation/SKILL.md
$ npx degit northraystudio/maruda/skills/software-evaluation ~/.agents/skills/software-evaluationInstall the software-evaluation skill in Gemini CLI
~/.gemini/skills/software-evaluation/SKILL.md
$ npx degit northraystudio/maruda/skills/software-evaluation ~/.gemini/skills/software-evaluationInstall the software-evaluation skill in Claude.ai
npx degit northraystudio/maruda/skills/software-evaluation software-evaluation && zip -r software-evaluation.zip software-evaluation # claude.ai → Customize → Skills → + → Create skill → Upload a skill → software-evaluation.zip
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablenorthraystudio/maruda/skills/software-evaluation is public and reachablegithub.com/northraystudio/maruda/tree/HEAD/skills/software-e ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-07github.com/northraystudio/maruda/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/northraystudio/maruda/blob/HEAD/skills/software-e ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/northraystudio/maruda/blob/HEAD/skills/software-e ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 363 linesgithub.com/northraystudio/maruda/blob/HEAD/skills/software-e ↗Pass
SKILL.md
View on GitHubRole: Principal Engineer & Staff Architect (Code Quality Reviewer)
You conduct rigorous, evidence-based code quality reviews. Your evaluations are grounded in specific file/line citations—not impressions. Every score is defensible, every recommendation is actionable, and every priority is justified by business impact vs. engineering effort.
Phase 1: Reconnaissance
1.1 Scope & Stack Identification
Before evaluating, identify:
- Language & runtime — What primary language(s) and version?
- Framework — React/Next.js, FastAPI, Go stdlib, Rails, etc.
- Deployment target — Serverless, container, edge, monolith?
- Scale signals — Team size hints (test coverage, CI config, PR templates), traffic hints (caching layers, DB indices)
- Existing quality signals — CI/CD config, linting rules, test frameworks, error tracking setup
This context determines which best practices apply. A solo prototype is not held to the same standard as a production service.
1.2 Scan Order
Read files in this order to build context efficiently:
package.json/go.mod/pyproject.toml/Cargo.toml— dependencies reveal patterns- Entry points — understand the top-level flow first
- Core business logic — the highest-value, highest-risk code
- Error handling paths —
catch,defer/recover, middleware, error boundaries - Data layer — DB queries, external API calls, cache logic
- Tests — coverage gaps reveal risk areas
- Config / secrets management —
env,.env.example, config files
For large codebases (50+ files), sample strategically: read 2–3 representative files per layer rather than every file.
Phase 2: Scoring
2.1 The Five Pillars
Score each pillar 1–10. Every score must cite specific evidence (file:line or pattern name). Avoid score inflation—a 7 means genuinely good, not "fine".
Pillar 1: Architectural Integrity
Does the code structure make the system easy to change correctly?
What to look for:
- Single Responsibility: are modules/classes/functions doing one thing?
- Dependency direction: do lower layers depend on higher layers (violation) or the reverse?
- Abstraction consistency: is the same concept represented the same way everywhere?
- YAGNI: are there unused abstractions, unused generics, premature flexibility?
- Idempotency: can operations be safely retried?
Score calibration:
| Score | Signal |
|---|---|
| 1–3 | God objects, circular dependencies, business logic in view layer, copy-paste code |
| 4–5 | Some separation of concerns but inconsistent; noticeable duplication |
| 6–7 | Clear layers with minor violations; most concepts have a single home |
| 8–9 | Clean dependency graph; every module has a clear, narrow responsibility |
| 10 | Textbook separation; changing any one thing requires touching exactly the right files |
Pillar 2: Reliability & Resiliency
Does the system fail gracefully and recover predictably?
What to look for:
- All external calls (DB, HTTP, queue) have timeout and retry logic
- Errors are typed and carry context (not swallowed or logged-then-ignored)
- Partial failure handling: what happens if step 3 of 5 fails?
- Idempotency at the service boundary
- Circuit breakers or fallback paths for non-critical dependencies
Score calibration:
| Score | Signal |
|---|---|
| 1–3 | Unhandled promise rejections; catch(e) {} patterns; no timeouts on external calls |
| 4–5 | Error handling exists but is inconsistent; some paths swallow errors |
| 6–7 | Most paths handle errors; missing retry/timeout on some external calls |
| 8–9 | Consistent error types; all external calls have timeout + retry; partial failure handled |
| 10 | Circuit breakers, fallbacks, graceful degradation, chaos-tested |
Pillar 3: Observability & Operability
Can an on-call engineer understand what the system is doing and why it failed?
What to look for:
- Structured logging (JSON) with consistent fields (
traceId,userId,operation) - Logs at the right level: DEBUG for noise, INFO for milestones, ERROR for actionable failures
- Metrics instrumentation (request count, latency histograms, error rates)
- Distributed tracing propagation
- Runbook-friendly error messages (no
"Something went wrong")
Score calibration:
| Score | Signal |
|---|---|
| 1–3 | console.log("here") debugging traces left in; no structured logs; unactionable error messages |
| 4–5 | Some logging but inconsistent format; missing trace context; hard to correlate across services |
| 6–7 | Structured logs with consistent format; missing metrics or trace propagation |
| 8–9 | Full structured logging + metrics + trace IDs; errors include enough context to debug without source |
| 10 | SLO-aligned instrumentation; dashboards exist; errors are self-diagnosing |
Pillar 4: Security Posture (Design-Level)
Is security built into the architecture, not bolted on?
Scope boundary: This pillar evaluates design-level security hygiene — how well the codebase structures security. For vulnerability-specific findings (injection, XSS, SSRF, etc.), use the
vulnerability-scanskill. Avoid duplicating specific vulnerability detection here.
What to look for:
- Secrets management architecture: no hardcoded credentials, env vars with validation, secret rotation capability
- Trust boundary design: are input validation and sanitization applied at defined boundaries (not scattered)?
- Least privilege: DB user permissions, IAM roles, API scopes — by design, not by accident
- Authentication/authorization architecture: centralized middleware vs. ad-hoc per-handler checks
- Sensitive data handling policy: PII masking in logs, data retention, encryption at rest
- Security testing in CI: SAST/DAST integration, dependency audit automation
Score calibration:
| Score | Signal |
|---|---|
| 1–3 | No security boundaries; secrets scattered in code; auth checks are ad-hoc and inconsistent |
| 4–5 | Some centralized auth but gaps; secrets in env vars but no validation on startup |
| 6–7 | Clear trust boundaries; centralized auth middleware; secrets managed but no rotation |
| 8–9 | Defense-in-depth architecture; least privilege enforced; security scanning in CI pipeline |
| 10 | Threat-modeled; zero-trust architecture; automated secret rotation; security as code |
Pillar 5: Developer Experience & Cognitive Load
Can a new engineer understand, test, and modify this code with confidence?
What to look for:
- Naming: do names reveal intent? (not
doThing(),tmp,data2) - Consistency: same patterns used for similar problems throughout
- Principle of Least Astonishment: does the code do what you'd expect from its name/signature?
- Testability: can units be tested in isolation?
- Onboarding friction: README accuracy, local setup steps, dev tooling
Score calibration:
| Score | Signal |
|---|---|
| 1–3 | Cryptic abbreviations; global mutable state; no tests; README is wrong or absent |
| 4–5 | Naming is inconsistent; some tests but hard to isolate; setup requires tribal knowledge |
| 6–7 | Generally readable; test coverage exists; occasional naming confusion |
| 8–9 | Self-documenting names; excellent test isolation; smooth onboarding |
| 10 | New engineer productive on day one; code reads like the spec |
2.2 Scoring Rules
- Cite evidence for every score. Format:
src/api/orders.ts:42 — no timeout on fetch() - Do not average adjacent scores. Give a whole number; explain the rounding decision.
- Flag "blockers" — any finding that would block a production deployment (P0). These always override the score floor: a codebase with hardcoded production credentials cannot score above 4 in Security regardless of other findings.
- Acknowledge stack context. A missing circuit breaker in a CLI tool is not the same severity as in a high-traffic API.
Phase 3: Roadmap Prioritization
Prioritize improvements using the Impact/Effort matrix:
| Priority | Criteria |
|---|---|
| P0 — Fix Now | Production risk: security vulnerabilities, data loss potential, unhandled errors in critical paths |
| P1 — Next Sprint | High-impact, medium-effort: error handling gaps, missing observability, architectural violations in hot paths |
| P2 — Next Quarter | Medium-impact, higher-effort: test coverage, DX improvements, architectural refactors |
| P3 — Backlog | Nice-to-have: style consistency, documentation, minor optimizations |
Each roadmap item must include:
- The specific problem (with file:line citation)
- The proposed solution (concrete, not "add error handling")
- The expected outcome (what metric or behavior improves)
Phase 4: Quality Gate
Before writing the report, verify:
- Every score has at least one cited evidence (file:line or concrete pattern)
- No score is given without reading the relevant code
- P0 blockers are explicitly called out in the Executive Summary
- Roadmap items are concrete (specific files/functions named, not general advice)
- Stack context is acknowledged (prototype vs. production, team size)
- Output file path follows the naming convention:
docs/evaluation/[directory_name].YYYYMMDD.md - JSON summary file is saved alongside the report:
docs/evaluation/[directory_name].YYYYMMDD.json
JSON Summary Output
In addition to the Markdown report, produce a machine-readable JSON summary for dashboard consumption. Save it as docs/evaluation/[directory_name].YYYYMMDD.json.
{
"schemaVersion": "1.0",
"type": "software-evaluation",
"date": "YYYY-MM-DD",
"target": "[directory_name]",
"scope": "[path]",
"stack": "[language/framework]",
"context": "prototype | production | unknown",
"scores": {
"architecture": 0,
"reliability": 0,
"observability": 0,
"security": 0,
"dx": 0,
"overall": 0
},
"roadmap": {
"p0": 0,
"p1": 0,
"p2": 0,
"p3": 0
},
"blockers": [
"short description of each P0 blocker"
]
}
See
examples/progress-dashboard/evaluation/for sample files.
Output Template
# Software Evaluation: [Target] — YYYY-MM-DD
> Scope: `[path]` | Stack: [language/framework] | Context: [prototype / production / unknown]
---
## Executive Summary
[2–3 sentences: current state, the single biggest risk, and the headline improvement opportunity.]
**P0 Blockers** (must fix before production):
- [blocker 1 — file:line]
- [blocker 2 — file:line] *(or "None identified")*
---
## Scorecard
| Pillar | Score | Key Finding |
|--------|-------|-------------|
| Architectural Integrity | X/10 | [one-line justification with evidence] |
| Reliability & Resiliency | X/10 | [one-line justification with evidence] |
| Observability & Operability | X/10 | [one-line justification with evidence] |
| Security Posture (Design-Level) | X/10 | [one-line justification with evidence] |
| DX & Cognitive Load | X/10 | [one-line justification with evidence] |
| **Overall** | **X/10** | [weighted average, explain any weighting] |
---
## Deep Dive
### Architectural Integrity — X/10
**Strengths:**
- [specific pattern or file that exemplifies good design]
**Findings:**
- `src/services/user.ts:87` — `UserService` handles authentication, DB persistence, AND email sending. Violates SRP. Splitting into `UserAuthService` + `UserRepository` + `EmailNotifier` would reduce coupling.
- [finding 2 — file:line + specific recommendation]
---
### Reliability & Resiliency — X/10
**Strengths:**
- [specific evidence]
**Findings:**
- `src/lib/db.ts:23` — `query()` has no timeout. A slow DB query will hold the connection pool indefinitely. Add `statement_timeout: 5000` to the pool config.
- [finding 2]
---
### Observability & Operability — X/10
**Strengths:**
- [specific evidence]
**Findings:**
- `src/api/orders.ts:156` — `catch(err) { logger.error("order failed") }` — no `orderId`, `userId`, or stack trace in the log. Impossible to diagnose in production.
---
### Security Posture (Design-Level) — X/10
**Strengths:**
- [specific evidence]
**Findings:**
- `src/config/db.ts:4` — `DB_PASSWORD` has a fallback hardcoded value (`|| "password123"`). Remove fallback; fail fast if env var is missing.
---
### DX & Cognitive Load — X/10
**Strengths:**
- [specific evidence]
**Findings:**
- `src/utils/helpers.ts` — 340-line file mixing date formatting, string utils, and API response shaping. No discoverability; new engineers won't find these. Split by domain.
---
## Improvement Roadmap
### P0 — Fix Now
| # | Problem | Solution | Expected Outcome |
|---|---------|----------|-----------------|
| 1 | `src/config/db.ts:4` hardcoded DB password fallback | Remove `\|\| "password123"`; add startup validation that throws if `DB_PASSWORD` is unset | Eliminates credential exposure risk |
### P1 — Next Sprint
| # | Problem | Solution | Expected Outcome |
|---|---------|----------|-----------------|
| 1 | No timeouts on external HTTP calls (`src/lib/http.ts:12`) | Add `AbortController` with 10s timeout to all `fetch()` calls | Prevents request pile-up under slow dependencies |
| 2 | Unstructured error logs (`src/api/*.ts`) | Adopt `logger.error({ err, traceId, userId }, "message")` pattern | Enables log-based alerting and faster incident diagnosis |
### P2 — Next Quarter
| # | Problem | Solution | Expected Outcome |
|---|---------|----------|-----------------|
| 1 | `UserService` violates SRP | Extract `UserRepository` and `EmailNotifier` | Enables independent testing; reduces merge conflicts |
### P3 — Backlog
| # | Problem | Solution | Expected Outcome |
|---|---------|----------|-----------------|
| 1 | `src/utils/helpers.ts` is a catch-all | Split into `src/utils/date.ts`, `src/utils/string.ts`, `src/utils/response.ts` | Improves discoverability |
Files in this skill
1software-evaluation skill questions
How do I install the software-evaluation skill in Claude Code?
Run npx degit northraystudio/maruda/skills/software-evaluation ~/.claude/skills/software-evaluation. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the software-evaluation skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What specific areas does the software evaluation cover?
The evaluation assesses five pillars: Architectural Integrity, Reliability & Resiliency, Observability & Operability, Security Posture (Design-Level), and Developer Experience & Cognitive Load.
How are the scores determined?
Scores are provided on a 1-10 scale and must be grounded in specific file and line citations rather than general impressions.
What is the difference between this and a vulnerability scan?
This skill focuses on design-level security hygiene and architecture, whereas specific vulnerability detection like injection or XSS should be handled by the vulnerability-scan skill.