What is QUALITY.md?

QUALITY.md is an{" "} open file format {" "} for declaring a project quality model: a holistic rubric of the desired quality characteristics (security, maintainability, code quality, test/spec quality, etc.), their quality requirements (guides, sensors, principles, standards, rules, specs), and the context (mission/purpose, user/stakeholder needs, risks, etc.) for why they matter.{" "}

The QUALITY.md format{" "} specification {" "} is designed to be agent, tool, and vendor agnostic. The companion `/quality`{" "} agent skill {" "} and `qualitymd`{" "} CLI {" "} serve as both a reference implementation and starter kit for working with `QUALITY.md` files, including the ability to create a comprehensive{" "} quality evaluation report {" "} with prioritized{" "} improvement recommendations {" "} ready for handoff or further review, useful for engineering quality loops or augmenting your existing workflow.

Why QUALITY.md?

Ensure stakeholders are aligned on what matters most and why
Identify the most impactful and low risk quality improvements
Build agentic control loops to continuously maintain and improve quality
Manage quality proactively instead of reactively
Tackle intent, comprehension, and technical debt
Move judgement and taste up the loop stack
Compound learning at the highest leverage point

Philosophy

Maintaining the quality of a thing is caring for it. When a thing exists for the benefit of another, caring for it well is caring for the other well.

The aim of QUALITY.md is to help others care well by making the practice of maintenance accessible to humans and agents.

How to use QUALITY.md?

Install the `/quality` agent skill:
```sh theme={null} npx skills add qualitymd/quality.md ```
Install the `qualitymd` CLI:
```sh theme={null} npm install -g quality.md ```
See getting started for other install methods.
Invoke `/quality setup` to create a tailored `QUALITY.md` for evaluation and continued refinement.

Run `/quality evaluate` to generate a holistic quality report with findings and actionable recommendations. See the [example quality evaluation report](https://github.com/qualitymd/quality.md/blob/main/examples/report-gallery/software-service/.quality/evaluations/0001-full-eval/report.md). Hand off quality improvement recommendations to inner agent loops, teammates, or the workflow best suited to the change. Run `/quality improve` to refine `QUALITY.md` from what the evaluation and improvement work revealed. Return to Evaluate with a sharper model and continue compounding quality learning.

Create your first QUALITY.md to establish a project quality model. Elevate quality evaluation and improvement up the loop stack. See project quality ratings by project area and quality factor. The open, vendor-neutral, QUALITY.md standard. Effortlessly set up, evaluate, and improve. QUALITY.md linting and management utilities.

FAQ

A quality model is an explicit, shared description of what "good" means for something you maintain. In QUALITY.md, that means the areas of a project, the quality factors that matter for each, and concrete requirements with checkable assessments — plus a rating scale for judging results and the context for why any of it matters. Instead of quality living in people's heads and scattered review comments, the model makes it visible enough for teams and agents to evaluate, align on, and improve. The idea has a long lineage. Manufacturing quality management (Shewhart's statistical quality control, Juran's "fitness for use") carried into software through McCall's and Boehm's models in the 1970s, HP's FURPS, Dromey's model, and the ISO 9126 and ISO 25010 standards. Across five decades the same pattern recurs: decompose quality into the characteristics that matter for a particular thing and its stakeholders, refine them into sub-characteristics, and tie those to assessable criteria. In practice, these models rarely spread beyond large organizations with formal quality programs: building and tailoring a detailed model was costly, and the metric-based rating methods meant to make quality measurable proved too reductive — or too complex — for everyday use. AI changes that. Agents make a tailored quality model cheap to establish and maintain, and inferential judging of quality requirements makes holistic evaluation accessible — good enough for many use cases where formal measurement never was. The [specification](/specification) defines the file format and its meaning: document structure (YAML frontmatter plus a Markdown body), the frontmatter schema for areas, factors, requirements, and the rating scale, naming and reference rules, and model semantics (how sources resolve, how requirements scope to their declaring area, how factors connect, and what the rating scale means). Conformance is a property of documents; the spec doesn't prescribe or certify any evaluation method. It's deliberately agent-, tool-, and vendor-agnostic. The [`/quality` skill](/skill) and [`qualitymd` CLI](/cli) are companions — a reference implementation and starter kit, not part of the format itself. No. The format is domain agnostic: it applies wherever you want to be deliberate about quality — documentation sets, data products, research reports, service operations, and more. There's no default factor checklist to import; each model earns its factors from the modeled thing's own needs and risks. Yes. The specification, `/quality` agent skill, and `qualitymd` CLI are all developed in the open at [github.com/qualitymd/quality.md](https://github.com/qualitymd/quality.md) and released under the MIT license. They're complementary layers. Rules files like AGENTS.md or CLAUDE.md tell an agent *how* to work in your project, and skills give it procedures for specific tasks — both steer the inner coding loop, action by action. `QUALITY.md` declares *what quality means*: the shared bar the resulting work is judged against. The `/quality` skill connects the two — it reads your `QUALITY.md` to evaluate the project and produces recommendations you can hand off to any agent, teammate, or workflow. In loop terms, rules and skills guide the inner loop; QUALITY.md powers the evaluation and improvement loops above it.