---
name: Qualitymd
description: Use when establishing or refining a project quality model, evaluating project quality against declared standards, generating improvement recommendations, or engineering quality loops into team workflows. Reach for this skill when you need to make quality criteria explicit, run evaluations to identify gaps and strengths, or hand off prioritized recommendations for improvement.
metadata:
    mintlify-proj: qualitymd
    version: "1.0"
---

# Quality.md Skill

## Product summary

Quality.md is an open file format and agent skill for declaring a project quality model: the areas of a project, the quality factors that matter for each, concrete requirements with checkable assessments, and a rating scale for judging results. The `/quality` agent skill and `qualitymd` CLI let you create a QUALITY.md file, evaluate your project against it, and generate prioritized improvement recommendations. Key files: `QUALITY.md` (the model file, YAML frontmatter + Markdown body). Key commands: `/quality setup` (create a model), `/quality evaluate` (run evaluation), `/quality improve` (refine the model). Primary docs: https://getquality.md

## When to use

Reach for this skill when:

- **Establishing quality criteria**: You need to make explicit what "good" means for a project — security, maintainability, test coverage, documentation, performance, or domain-specific factors.
- **Evaluating project health**: You want a holistic assessment of a project against declared standards, with findings and ratings by area and factor.
- **Generating improvement recommendations**: You need prioritized, actionable recommendations for quality work, ranked by impact and confidence.
- **Engineering quality loops**: You're building recurring evaluation into team workflows (GitHub Actions, Claude Code routines, Codex tasks) to maintain quality over time.
- **Aligning stakeholders**: You need a shared, documented model of quality expectations so teams and agents evaluate work consistently.
- **Compounding learning**: You want to refine your quality model based on what evaluations reveal, improving the model itself over time.

Do not use this skill for: authentication setup, pricing/account management, or dashboard-only operations.

## Quick reference

### Core commands

| Command | Purpose |
|---------|---------|
| `/quality setup` | Guided creation of a tailored QUALITY.md for your project |
| `/quality evaluate` | Run a complete evaluation, produce findings and recommendations |
| `/quality improve` | Refine QUALITY.md based on evaluation results and learning |
| `/quality update` | Update the skill and CLI to latest versions |

### CLI commands (when running directly)

| Command | Purpose |
|---------|---------|
| `qualitymd init [path]` | Scaffold a starter QUALITY.md file |
| `qualitymd lint [path]` | Validate a QUALITY.md file for conformance |
| `qualitymd evaluation run` | Execute evaluation with deterministic runner |
| `qualitymd model tree [path]` | Render model as a containment hierarchy |
| `qualitymd model list [path]` | Enumerate model elements with canonical IDs |
| `qualitymd status [path]` | Show workspace status snapshot |

### QUALITY.md file structure

```yaml
---
title: <string>                    # Required: model name
description: <string>              # Optional: model description
ratingScale:                       # Required: ordered best-to-worst
  - level: <id>                    # Unique level ID
    title: <string>                # Human label
    criterion: <string>            # Default judgment rule
    description: <string>          # Recommended: level meaning
factors:                           # Optional: quality characteristics
  <factor-name>:
    title: <string>
    description: <string>
    requirements:
      <requirement-name>:
        title: <string>
        assessment: <string>       # How to assess this requirement
        factors: [<factor-refs>]   # Connect to factors
requirements:                      # Optional: direct area requirements
  <requirement-name>:
    title: <string>
    assessment: <string>
    factors: [<factor-refs>]       # Required for direct requirements
areas:                             # Optional: nested project areas
  <area-name>:
    title: <string>
    source: <string>               # What to evaluate (path, glob, or prose)
    factors: {...}
    requirements: {...}
    areas: {...}
source: <string>                   # Optional: default source (directory)
---

# Model context (Markdown body)
Document why this quality model matters, stakeholder needs, risks, and context.
```

### Model reference syntax

| Reference type | Format | Example |
|---|---|---|
| Area | `area:<path>` | `area:root`, `area:webhooks/delivery` |
| Factor | `factor:<area>::<path>` | `factor:root::security`, `factor:webhooks/delivery::reliability/retry` |
| Requirement | `requirement:<area>::<name>` | `requirement:root::release-notes-current` |
| Rating level | `rating:<level-id>` | `rating:target`, `rating:unacceptable` |

### Evaluation output structure

Evaluations produce:
- `evaluation.json`: Structured findings, ratings, and metadata
- `report.md`: Human-readable report with ratings, findings, and recommendations
- `recommendations.md`: Prioritized improvement actions
- Logs under `.quality/logs/`

## Decision guidance

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

| Situation | Use |
|-----------|-----|
| First time, need guidance | `/quality setup` — interactive, agent-guided creation |
| Scripting or CI/CD | `qualitymd init` — deterministic CLI, minimal template |
| Want to customize heavily | `qualitymd init --minimal` — skeleton only, no prose |

### When to scope evaluation

| Goal | Approach |
|------|----------|
| Full project assessment | `/quality evaluate` (no flags) |
| Single area deep dive | `/quality evaluate --area area:webhooks` |
| Factor-specific review | `/quality evaluate --factor factor:root::security` |
| Recurring scheduled runs | Use Claude Code routine or Codex task with explicit scope |

### When to use harness vs. agent evaluator

| Evaluator | When to use |
|-----------|------------|
| `harness` (default) | Local evaluation, no API key needed, uses current agent session |
| `claude` | Explicit Claude API evaluation (requires credential) |
| `codex` | Explicit Codex evaluation (requires credential) |

## Workflow

### Typical quality loop: establish, evaluate, improve

1. **Establish the model** (`/quality setup`)
   - Run `/quality setup` with an agent to create a tailored QUALITY.md
   - The agent asks about your project's areas, quality factors, and requirements
   - Review the generated QUALITY.md; edit to refine factors, requirements, and assessment methods
   - Commit QUALITY.md to version control

2. **Evaluate the project** (`/quality evaluate`)
   - Run `/quality evaluate` to assess the project against the model
   - The skill produces findings (gaps, risks, strengths, notes) for each requirement
   - Findings are rated against the rating scale (e.g., target, minimum, unacceptable)
   - Factors and areas roll up from requirement ratings
   - Review the generated report and recommendations

3. **Act on recommendations** (handoff or implementation)
   - Read the prioritized recommendations in `recommendations.md`
   - Hand off recommendations to teammates, inner agent loops, or GitHub Issues/Linear
   - Implement or delegate the work

4. **Improve the model** (`/quality improve`)
   - Run `/quality improve` to refine QUALITY.md based on what the evaluation revealed
   - The agent suggests refinements: clearer requirements, better assessments, adjusted factors
   - Update the model; commit the changes
   - Return to step 2 with a sharper model

5. **Loop** (recurring evaluation)
   - Set up a Claude Code routine or Codex task to run `/quality evaluate` on a schedule
   - Commit evaluation artifacts back to the repository
   - Use the recurring reports to track quality trends and compound learning

### Scoped evaluation workflow

1. **Identify the scope**: area, factor, or full model
2. **Run evaluation**: `/quality evaluate --area area:webhooks` (or `--factor`)
3. **Review findings**: Read the scoped report; findings are specific to that scope
4. **Act**: Implement recommendations for the scoped area
5. **Improve**: Refine requirements or factors in that area based on findings

### Recurring evaluation in Claude Code

1. **Commit the skill** to the repository so fresh clones carry it
2. **Install qualitymd** in the environment setup script (npm, pnpm, or hosted installer)
3. **Create a routine** with an explicit prompt:
   ```
   Run /quality evaluate for the repository's QUALITY.md. When complete, 
   commit the new evaluation run folder and open a pull request summarizing 
   the rating, top findings, and top recommendations.
   ```
4. **Grant permissions**: Write access to `.quality/evaluations/` and `.quality/logs/`
5. **Monitor**: Use `qualitymd status --json` and `qualitymd evaluation list --json` to track runs

## Common gotchas

- **Missing `factors` on direct area requirements**: A requirement declared directly under an area (not under a factor) MUST declare `factors` with at least one entry. Omitting it makes the document non-conforming.
- **Ambiguous factor names**: Avoid reusing the same factor name anywhere in an area's recursive factor tree; it makes authored references ambiguous to readers and tools.
- **Assessment must be a scalar**: `assessment` MUST be a single non-empty string, not a list. Copying multiple criteria as a list is invalid.
- **Source inheritance**: Child areas inherit the source of the nearest ancestor that declares one. Declaring a child area narrows attention to that area's source; it does not re-apply ancestor requirements to the child.
- **Requirement scope**: Requirements are scoped to the area where they are declared. Child areas do not inherit ancestor requirements. The same material can be subject to requirements on multiple areas, each read at its own scope.
- **Rating level order matters**: Rating levels are ordered best-to-worst in the scale. The order is part of the meaning; do not reorder levels after evaluation without understanding the impact.
- **Unattended evaluation**: When evaluation runs unattended (Claude Code routine, Codex task), it advances checkpoint by checkpoint with no interactive gates. An `awaiting_evaluator` receipt is normal progress; resume the run with `qualitymd evaluation run --resume <run>`.
- **Interrupted runs**: Every checkpoint is persisted in `evaluation.json`. If a session stops mid-run, the next session resumes with `qualitymd evaluation run --resume <run> --json`.
- **No nested agent process**: Harness-backed evaluation does not launch a second Claude or Codex session; it exchanges JSON with the current one. No API key is needed beyond the running agent.
- **Evaluation does not change the model**: Evaluation produces findings and recommendations; it does not modify QUALITY.md. Use `/quality improve` to refine the model based on evaluation results.

## Verification checklist

Before submitting work with Quality.md:

- [ ] QUALITY.md is valid: run `qualitymd lint QUALITY.md` with no errors
- [ ] Model structure is sound: run `qualitymd model tree QUALITY.md` and verify areas, factors, requirements are as intended
- [ ] Every requirement has at least one factor connection (direct or via placement)
- [ ] Direct area requirements declare `factors` with at least one entry
- [ ] Assessment fields are scalars (strings), not lists
- [ ] Rating scale is ordered best-to-worst and has at least two levels
- [ ] Evaluation runs without errors: `qualitymd evaluation run --model QUALITY.md --dry-run` succeeds
- [ ] Report is generated: `evaluation.json` and `report.md` exist in the evaluation run folder
- [ ] Recommendations are actionable: `recommendations.md` lists concrete next moves with rationale
- [ ] Model is committed: QUALITY.md is in version control
- [ ] Evaluation artifacts are committed: `.quality/evaluations/<run>/` folder is in version control (for recurring loops)

## Resources

- **Comprehensive navigation**: https://getquality.md/llms.txt — page-by-page reference for all documentation
- **Specification**: https://getquality.md/specification — formal QUALITY.md format, model vocabulary, and semantics
- **Engineering loops**: https://getquality.md/loops — how to integrate evaluation and improvement into team workflows
- **CLI reference**: https://getquality.md/cli — all deterministic commands and flags

---

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