Skip to main content

QUALITY.md

Open formatAgent skillCLI

Engineer loops to improve project quality, aligning your team and agents on what quality means for what matters most.

Getting startedEngineer quality loopsRead the spec

What is QUALITY.md?

QUALITY.md is anopen file formatfor 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 formatspecificationis designed to be agent, tool, and vendor agnostic. The companion /qualityagent skilland qualitymdCLIserve as both a reference implementation and starter kit for working with QUALITY.md files, including the ability to create a comprehensivequality evaluation reportwith prioritizedimprovement recommendationsready 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?

1

Set up

  1. Install the /quality agent skill:

    npx skills add qualitymd/quality.md

  2. Install the qualitymd CLI:

    npm install -g quality.md

    See getting started for other install methods.

  3. Invoke /quality setup to create a tailored QUALITY.md for evaluation and continued refinement.

2

Evaluate

Run /quality evaluate to generate a holistic quality report with findings and actionable recommendations. See the example quality evaluation report.
3

Act

Hand off quality improvement recommendations to inner agent loops, teammates, or the workflow best suited to the change.
4

Improve

Run /quality improve to refine QUALITY.md from what the evaluation and improvement work revealed.
5

Loop

Return to Evaluate with a sharper model and continue compounding quality learning.

Quickstart

Create your first QUALITY.md to establish a project quality model.

Engineer the Quality Loop

Elevate quality evaluation and improvement up the loop stack.

Example quality evaluation

See project quality ratings by project area and quality factor.

Specification

The open, vendor-neutral, QUALITY.md standard.

/quality agent skill

Effortlessly set up, evaluate, and improve.

CLI reference

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 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 and qualitymd 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 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.