jsmastery-pro/skills: a phase-based agent workflow that keeps state in files

The problem: agent work that evaporates when the session closes

Most AI coding sessions end the same way. The context is gone, the reasoning behind a decision is gone, and the next session starts by re-explaining the project. The repository states the fix directly: the state lives in files (a scope, specs, AGENTS.md, tests), not in a chat session, so work survives across sessions and works for a whole team.

The audience is narrow and specific. You need an agent that reads Agent Skills, which the README lists as Claude Code, Cursor, Codex and Gemini CLI, among others linked from agentskills.io. If you are a solo developer doing one-off scripts, the file scaffolding is overhead you will not recover. If you are on a team where one person designs the data model and another builds the feature three days later, the artifacts are the point.

The workflow is phase-based rather than conversational. Each skill owns one phase, and the README is explicit that you run only the ones a change needs, in any order. That is a deliberate rejection of the single mega-prompt, and it means the value depends on you choosing the right subset.

How the skills hand work to each other

There are nine skills. scope turns an idea into a living, coarse plan. audit writes the AGENTS.md context files that every other skill reads. architect makes a load bearing decision and writes it as a build spec in docs/specs/. develop builds from that spec. check confirms a change before merge, with /check verify running the real app and /check review reading the code on a second model. test writes a suite for the code you just changed. document writes PR text, changelog, release note or postmortem from the real diff. sync keeps AGENTS.md, the scope and spec statuses current. debug finds and fixes a root cause, then hands a regression test to /test.

The interesting mechanism is the gate between develop and architect. If building would mean inventing an undecided design, provider or data model, /develop stops and routes you to /architect. You can override and build anyway, but the README says the override is not free: the assumption is recorded as an Assumed spec in docs/specs/ and flagged on the feature until /architect ratifies it. The flag does not block you from marking the feature done. It is a standing reminder, not a lock.

The README describes this as layered rather than magic. /architect names the source of every value a feature must produce, /develop rechecks that coverage before building, and at Beta or above /architect recommends an independent cross-model critic over the spec. The README concedes it catches the vast majority, not everything, and points to /check verify and /test for behavioral correctness.

Installing the skills and running a first real change

Installation goes through npx skills, which the README links to the vercel-labs/skills repository. The package.json declares Node >=18, so check that first. Pick the command for your agent.

# Claude Code (installs into .claude/skills, then restart Claude Code)
npx skills@latest add jsmastery-pro/skills -a claude-code

For a generic .agents/skills directory read by Codex and other agents, drop the -a flag.

# Generic .agents/skills, read by Codex and other agents
npx skills@latest add jsmastery-pro/skills

After the Claude Code install, restart the client so it picks up the new skills. The README says to commit the installed skills folder so the workflow is shared with the team.

For an existing codebase the README gives a specific order: /audit first so every skill understands your project, then /scope the next slice on top of what exists, then the feature loop. For a new product it inverts: /scope the idea, /architect the stack, scaffold the project, then /audit to seed AGENTS.md from the real project, because the stack is decided and the project scaffolded before /audit runs, so it reads a real project rather than an empty one.

At the end of /scope you pick a workflow depth. Prototype is just /develop, self-checked, for throwaway work. Alpha adds /check verify. Beta adds /test. GA adds a fresh-model /check review and /document. A bare /scope run at any time shows where things stand. The repository also ships two maintenance scripts in package.json: npm run check runs node scripts/check-portability.mjs, and npm run tokens runs node scripts/analyze-token-usage.mjs.

The workflow depth setting is a suggestion, not an enforcement layer

This is where the project makes a trade-off worth naming. The README says the depth is a suggested checking tail after /develop, never a track you are locked onto, and that you run or skip any step and mark a feature done when you decide it is. The one thing the workflow asks at every depth is that a load bearing decision gets written down.

That means nothing mechanically stops a Prototype-depth change from reaching production. The gate that does exist is the Assumed spec flag, and the README is clear that it does not block marking done. If your team needs a hard merge gate, this is the wrong tool. You would be adding a policy layer on top of a system that deliberately declines to be one.

The second constraint is the docs directory. The README notes that if docs/ is a published docs site, the workflow artifacts move to .workflow/ so they do not ship with your site. That relocation is a manual decision you have to make before the first run, not something the skills detect.

Third, hardening, described as systems level failure mode analysis, is temporarily removed and will return as a system design specialization. If failure mode analysis at the systems level is what you came for, it is not in the current set.

Where the artifacts land, and why that matters for review

The README gives an ownership table. Scope goes to docs/scope/ and is owned by scope. Specs go to docs/specs/ and are owned by architect. Context files are AGENTS.md plus a thin CLAUDE.md pointer, owned by audit and kept current by sync. The design system is design.md for art direction, with token values living in CSS, owned by develop. Review findings go to docs/reviews/ and are owned by check. Tests go to your test dirs. App code goes to your source tree. Human docs are the PR body, CHANGELOG.md, docs/releases/ and docs/postmortems/, owned by document.

The design system split is the detail most likely to surprise people. design.md holds art direction, but the actual token values live in CSS. If you expect design.md to be a token source of truth you can import from, it is not.

Because state lives in files, each skill suggests /clear at handoffs. A fresh session reads from disk again, and long chats do not pile up cost. That is a real operational difference from workflows that keep one thread alive for days. The cost is that anything not written to disk is lost at the handoff, so the discipline of writing the spec first is load bearing in a way the README does not overstate.

How this differs from a single agent prompt or a CI pipeline

The nearest comparison is the pattern most teams already use: one long system prompt that tells the agent to plan, implement, test and document. That approach keeps everything in one context window, which is simpler to start and cheaper to set up. The difference in approach here is decomposition plus persistence. Each phase is a separate skill file, and the handoff happens through files on disk rather than through accumulated context. You get resumability and team sharing; you pay with more artifacts to maintain and a handoff step where context is deliberately dropped.

The other comparison is CI. A pipeline enforces checks mechanically: a failing test blocks a merge. This repository does not do that. The README frames the depth setting as a suggested tail and says you are in charge. So CI and this workflow occupy different slots. CI decides whether code may merge; these skills decide what gets built and whether a decision was recorded. Teams that conflate the two will be disappointed by the absence of a hard gate.

A third, smaller difference: /check review reads the code on a second model, and at Beta or above /architect recommends an independent cross-model critic over the spec. Cross-model review is a deliberate design choice, not an incidental one, and it is the part hardest to replicate with a single-agent prompt.

Maintenance, licence and upgrade cost

The repository is MIT licensed, with the licence field set in package.json and a LICENSE file at the top level. MIT is permissive, so you can commit the installed skills folder into a private repository as the README suggests. This is not legal advice; if you redistribute the skills inside a commercial product, read the LICENSE file yourself rather than relying on the SPDX identifier.

The last push to the default branch was on 2026-08-09, roughly six weeks before this writing, and the repository is not archived. The version in package.json is 2.0.0. No releases were retrieved, so the version number in package.json is the only version signal available.

The upgrade cost is mostly re-reading. Each skill's instructions live in its SKILL.md, which is what every client reads. The agents/openai.yaml beside it is interface metadata only, carrying the name, blurb and opening prompt Codex shows in its agent picker, and the README states it carries no logic of its own. So an upgrade that changes behaviour will show up in SKILL.md files, and an upgrade that only changes how Codex presents the skill will show up in the YAML. If you have customized SKILL.md locally, a reinstall can overwrite that. The README does not document a merge or rollback path for locally modified skills, so keep your edits in a separate branch or note the diff before reinstalling. The npm run check script, which runs the portability checker, is the one automated check the repository ships.

Editorial conclusion

Adopt it if your team already runs an Agent Skills client and wants scope, specs and review findings to survive across sessions instead of dying in a chat window. Skip it if you want a deterministic pipeline: the README describes the depth setting as a suggested checking tail, and every check can be skipped. Before committing, read docs/workflow-guide.md end to end, then run npx skills@latest add jsmastery-pro/skills -a claude-code and confirm the skills land in .claude/skills and that a bare /scope reports where things stand.

Frequently asked questions

Official sources

1. Issues
2. jsmastery-pro/skills on GitHub
3. License: MIT
4. Project website
5. README