---
name: Qualitymd
description: Use when modeling project quality, evaluating code or documentation against quality standards, generating improvement recommendations, or engineering quality loops. Reach for this skill when you need to establish what "good" means for a project, assess it systematically, and compound learning over time.
metadata:
    mintlify-proj: qualitymd
    version: "1.0"
---

# Quality.md Skill

## Product summary

Quality.md is an open format and toolchain for declaring a project quality model — a holistic rubric of desired quality characteristics (security, maintainability, test coverage, etc.), their requirements, and the context for why they matter. The `/quality` agent skill and `qualitymd` CLI let you create a `QUALITY.md` file (YAML frontmatter + Markdown body), evaluate a project against it to produce findings and recommendations, and refine the model based on what you learn.

**Key files and commands:**
- `QUALITY.md` — the quality model file (YAML frontmatter + Markdown body)
- `/quality setup` — guided creation of an initial model
- `/quality evaluate` — produce a comprehensive quality report with findings and recommendations
- `/quality improve` — refine the model from evaluation results
- `qualitymd` CLI — deterministic tooling for linting, querying, and managing evaluations

**Primary docs:** https://getquality.md

## When to use

Reach for this skill when:

- **Establishing quality standards:** A project needs an explicit, shared definition of what "good" means — the areas that matter, quality factors for each, and concrete requirements with checkable assessments.
- **Evaluating project quality:** You need to assess a codebase, documentation set, data product, or service against a quality model and produce a prioritized list of improvement recommendations.
- **Aligning teams:** Stakeholders disagree on quality priorities or what matters most; a quality model makes those judgments visible and testable.
- **Engineering quality loops:** You want to move quality judgment up the loop stack — from ad hoc reviews to systematic, recurring evaluation and improvement.
- **Compounding learning:** Each evaluation should refine the model, making future evaluations sharper and more actionable.

Do not use this skill for: authentication, deployment, infrastructure, or operational dashboards. Quality.md is about modeling and evaluating quality, not running systems.

## Quick reference

### File structure

A `QUALITY.md` file has two layers:

```markdown
---
title: <string>                    # Required: model name
description: <string>             # Optional: model purpose
ratingScale:                       # Required: ordered levels (best to worst)
  - level: <id>                    # Unique ID (e.g., "target", "minimum")
    title: <string>               # Display label
    criterion: <string>           # Default rating rule
areas:                            # Optional: entities being evaluated
  <area-name>:
    title: <string>
    source: <path/glob>           # What to evaluate (inherits from parent)
    factors:                       # Quality dimensions
      <factor-name>:
        title: <string>
        requirements:
          <requirement-name>:
            title: <string>
            assessment: <string>   # How to check it
            factors: [<factor-name>]
---

# Model context

Document scope, stakeholder needs, risks, and rationale for the model.
```

### Skill commands

| Command | Purpose |
|---------|---------|
| `/quality setup` | Guided creation of a tailored `QUALITY.md` |
| `/quality evaluate` | Generate evaluation report with findings and recommendations |
| `/quality improve` | Refine `QUALITY.md` based on evaluation results |
| `/quality update` | Update skill and CLI to latest versions |

### CLI commands (use when you need deterministic output)

| Command | Purpose |
|---------|---------|
| `qualitymd init [path]` | Scaffold a starter `QUALITY.md` |
| `qualitymd lint [path]` | Validate a `QUALITY.md` file |
| `qualitymd model tree` | Show model structure as hierarchy |
| `qualitymd model list` | Enumerate all model elements with IDs |
| `qualitymd evaluation create` | Create a numbered evaluation run folder |
| `qualitymd evaluation report build` | Build deterministic reports from evaluation data |

### Model references (canonical IDs)

Use these formats when referencing model elements:

- **Area:** `area:root` or `area:webhooks/delivery`
- **Factor:** `factor:root::security` or `factor:webhooks/delivery::reliability/retry-behavior`
- **Requirement:** `requirement:root::release-notes-current`
- **Rating level:** `rating:target`

## Decision guidance

### When to use `/quality setup` vs `qualitymd init`

| Situation | Use |
|-----------|-----|
| Creating a model for the first time; want guided, interactive help | `/quality setup` (through agent) |
| Scripting or CI/CD; need deterministic output; want minimal template | `qualitymd init --minimal` |
| Want a full template with prose and examples to edit | `qualitymd init` (CLI) |

### When to scope evaluation by Area vs Factor

| Goal | Approach |
|------|----------|
| Evaluate one subsystem or service | Scope by Area (e.g., `area:webhooks/delivery`) |
| Focus on one quality dimension across the whole project | Scope by Factor (e.g., `factor:root::security`) |
| Full project assessment | No scope filter; evaluate everything |

### When to use Areas vs Factors

| Concept | Use for |
|---------|---------|
| **Area** | Entities being evaluated: services, modules, documentation sets, data products. Areas can nest. |
| **Factor** | Quality dimensions: security, maintainability, performance, test coverage. Factors group related requirements. |

## Workflow

### 1. Create or refine the quality model

**First time:**
- Run `/quality setup` with an agent for guided creation.
- The agent will ask about project scope, stakeholder needs, quality areas, and factors.
- Review the generated `QUALITY.md` and edit the Markdown body to document context, risks, and rationale.

**Subsequent times:**
- Run `/quality improve` after an evaluation to refine the model based on what you learned.
- Update requirements, factors, or rating criteria as your understanding sharpens.

### 2. Evaluate the project

- Run `/quality evaluate` to produce a comprehensive quality report.
- The report includes:
  - Findings (gaps, risks, strengths, notes) for each requirement
  - Rating results for requirements, factors, and areas
  - Improvement recommendations ranked by impact and confidence
  - Key gaps and top findings

### 3. Review and act

- Read the evaluation report by area and factor.
- Identify handoff-ready recommendations.
- Delegate or implement recommendations through your normal workflow (GitHub Issues, Linear, pull requests, etc.).

### 4. Improve the model

- Run `/quality improve` to refine `QUALITY.md` based on evaluation results and improvement work.
- Update requirements that proved unclear or misaligned.
- Add factors or areas you discovered matter more than expected.
- Adjust the rating scale if levels don't map well to your project's reality.

### 5. Loop

- Return to step 2 with a sharper model.
- Each cycle compounds learning and makes recommendations more actionable.

## Common gotchas

- **Missing `factors` on direct area requirements:** A Requirement declared directly under an Area (not nested under a Factor) MUST declare `factors` with at least one entry. Nested requirements inherit their containing Factor automatically.

- **Assessment must be a scalar:** `assessment` MUST be a single string, not a list. Reference a specification or guide once instead of copying criteria that would drift.

- **Rating Scale must be ordered best-to-worst:** The first level is best; the last is worst. Tools rely on this ordering for aggregation.

- **Source paths are relative to QUALITY.md:** If your model is at `docs/QUALITY.md`, a source of `src/` resolves to `docs/src/`. Use absolute paths or globs if you need different behavior.

- **Child Areas don't inherit parent Requirements:** An ancestor Area's Requirements evaluate against the ancestor's Source, not the child's. This is intentional — it lets you scope requirements precisely.

- **Unqualified references in durable output:** Never persist unqualified references (e.g., `security` instead of `factor:root::security`) in evaluation data or reports. Always use qualified canonical IDs.

- **`not assessed` is not a rating level:** When evidence is insufficient to rate a requirement, the result is `not assessed`, not a low rating. Keep this distinct in reports and analysis.

- **Evaluation scope must be declared upfront:** You can't change scope mid-evaluation. Create a new evaluation run if you need a different scope.

## Verification checklist

Before submitting work with Quality.md:

- [ ] `QUALITY.md` file exists and is valid (run `qualitymd lint`)
- [ ] All Areas have a `title` and at least one Factor or Requirement
- [ ] All Factors have a `title`
- [ ] All Requirements have a `title`, `assessment` (scalar), and `factors` reference(s)
- [ ] Rating Scale has at least two levels, ordered best-to-worst, each with `level`, `title`, and `criterion`
- [ ] Model references use qualified canonical IDs (`area:`, `factor:`, `requirement:`, `rating:`)
- [ ] Markdown body documents scope, stakeholder needs, risks, and rationale
- [ ] Evaluation report includes findings, ratings, and recommendations
- [ ] Recommendations are prioritized by impact and confidence
- [ ] No circular Area nesting or self-referential Factors

## Resources

**Comprehensive navigation:** https://getquality.md/llms.txt

**Critical pages:**
- [Specification](https://getquality.md/specification) — authoritative format definition, frontmatter schema, evaluation semantics
- [Engineering quality loops](https://getquality.md/loops) — how to integrate evaluation and improvement into recurring workflows
- [CLI reference](https://getquality.md/cli) — deterministic commands for linting, querying, and managing evaluations

---

> For additional documentation and navigation, see: https://getquality.md/llms.txt