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?

npx skills add qualitymd/quality.md

npm install -g quality.md

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

What is a quality model?

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.

What's covered by the formal QUALITY.md specification?

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.

Is QUALITY.md only for modeling software quality?

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.

Is QUALITY.md open source? How is it licensed?

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.

How does QUALITY.md relate to agent skills and rules (e.g. AGENTS.md/CLAUDE.md)?

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.

⌘I