What is a way

A way is a team's way of working, packaged: its gated phases, the documents each phase must produce, the knowledge and rules it carries, and the tools, environment variables, and MCP servers it requires. All of it declared in one portable, versioned, agent-neutral manifest (way.yaml).

If npm is how a library reaches every project, ways is how a way of working reaches every repo: the same versions-lockfile-registry model — add, install, pins, approvals — applied to the process instead of the code.

ways is the CLI that makes that manifest real:

npx ways.sh add <source>    # acquire pinned → see the full plan → approve → install
npx ways.sh bind            # bind the way's capability slots to YOUR tools
npx ways.sh doctor          # validate the whole environment, honestly
npx ways.sh install         # reproduce the whole ways.lock on a fresh clone / in CI

The 30-second mental model

1. A way author writes way.yaml: skills, knowledge, requirements, capability slots, and the flow (phases → gates → generated documents).
2. A consumer runs ways add: the way is fetched pinned, validated against the schema and the conformance rules, scanned by Ways Shield for content that isn't safe to place, and nothing executable is enabled until the full plan is approved.
3. The consumer runs ways bind to fill the way's slots with their tools. The way says it needs a version-control host; your repo says that host is GitHub, and your client's repo says GitLab. Same way, same commit, two toolchains.
4. ways doctor proves the environment is ready, or tells you exactly what to fix.
5. Every teammate (and CI) runs ways install to reproduce that exact set from ways.lock, byte-for-byte, with the approval carried in the lock so trusted content isn't re-prompted.

One way, or a whole family

A way.yaml describes one gated flow. To ship several related flows under one identity — a feature flow and a bug flow, say, each with its own gates — package them as a WayFamily: it references member ways and carries the payload they share, so ways add installs the whole set in one command while each member stays installable on its own.

How it relates to skills.sh and steering

Packaging and placement ride the substrates that already work: skills land via skills.sh, rules land via steering (converted to each agent's native format), and MCP dependencies are described with the standard server.json vocabulary. ways never copies skill files itself and never targets a single agent.

What it adds on top of them is the contract:

Install / invocation

The CLI is published under three names. Same tool, pick whichever you prefer:

npx ways (no suffix) does not work: that unscoped name belongs to an unrelated npm package. All three expose the ways bin:

npm i -g ways.sh    # then: ways add <source>

Continue with Getting started, or go straight to ways & families.

Normative source of truth: the ways repo — the schemas in schemas/ways/v1alpha1/, and the author-way / author-way-family skills in skills/ that write a manifest for you.