Engineer loops to improve project quality, aligning your team and agents on what quality means for what matters most.
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?
Set up
Install the
/qualityagent skill:Install the
qualitymdCLI:See getting started for other install methods.
Invoke
/quality setupto create a tailoredQUALITY.mdfor evaluation and continued refinement.
Act
Hand off quality improvement recommendations to inner agent loops, teammates, or the workflow best suited to the change.
Improve
Run /quality improve to refine QUALITY.md from what the evaluation
and improvement work revealed.
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.
What's covered by the formal QUALITY.md specification?
What's covered by the formal QUALITY.md specification?
/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?
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?
Is QUALITY.md open source? How is it licensed?
/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)?
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.