jsmastery-pro/skills: Phase-Based Engineering Workflow for AI Coding Agents

What jsmastery-pro/skills Solves for Engineering Teams Using AI Agents

When an AI coding agent works through a large change, it faces two practical problems: it may not know enough about the project to make good architectural decisions, and any context it builds up during a long session disappears when the session ends. The @jsmastery/skills package addresses both by imposing a phase structure and storing the output of each phase in the repository as files.

The target audience is developers using AI coding agents (Claude Code, Cursor, Codex, Gemini CLI, and others on the Agent Skills platform at agentskills.io) who want those agents to follow a consistent engineering process rather than working from scratch each session. Each skill handles one phase: writing a coarse scope, auditing the codebase into an AGENTS.md file, designing an architecture spec, building from that spec, verifying the result, writing tests, documenting the change, and syncing the context files. The README summarizes the chain as: idea -> /scope -> /audit -> /architect -> /develop -> /check verify -> /test -> /check review -> /document -> /sync.

The Nine Skills and What Each Phase Produces

Each skill writes its output to a predictable location in the repository:

- /scope writes to docs/scope/ and maintains a living coarse plan of what to build, in order. It works for greenfield (run first) and brownfield (enrolls what exists, then plans new work) projects. - /audit writes AGENTS.md context files that give every other skill the project's stack, commands, and conventions. For a monorepo, it writes one AGENTS.md per workspace. - /architect runs a design conversation and writes the decision as a build spec to docs/specs/. It also writes a thin CLAUDE.md pointer that points agents to AGENTS.md. - /develop builds a feature or UI from its spec. If no spec exists for a required decision, it stops and asks for /architect to run first. An override is possible but records the assumption as an Assumed spec in docs/specs/ and flags the feature until /architect ratifies it. - /check runs in two modes: /check verify runs the real app to confirm the change works; /check review uses a second model to read the code. - /test writes a test suite for the code just changed, in whatever test directories the project uses. - /document writes the PR body, CHANGELOG.md, release notes, or postmortem from the real diff, stored under docs/releases/ or docs/postmortems/. - /sync keeps AGENTS.md, the scope file, and spec statuses current after a change. - /debug finds and fixes the root cause of a bug, then hands a regression test to /test.

Review findings from /check are stored in docs/reviews/. If docs/ is a published documentation site, the workflow's own files move to .workflow/ to avoid shipping them.

Installing Skills in Claude Code, Codex, and Cursor

The package uses the Agent Skills distribution system and installs with npx.

For Claude Code, run this command (Claude Code must be restarted after installation):

npx skills@latest add jsmastery-pro/skills -a claude-code

This writes the skill files into .claude/skills. For Codex or other agents that read a generic skills directory:

npx skills@latest add jsmastery-pro/skills

This writes to .agents/skills. Committing the installed skills folder to the repository shares the workflow with everyone on the team without requiring each person to run the install command. The agent parameter (-a claude-code) is optional; without it, the generic path is used.

Requires Node.js 18 or later, as declared in the package.json engines field. Each skill's instructions live in its SKILL.md file, which is what every client reads. The agents/openai.yaml file beside each skill is interface metadata only (the name and opening prompt shown in Codex's agent picker) and carries no logic.

File-Based State and Multi-Session Continuity

The most important architectural choice in this workflow is that state lives in files, not in the chat session. The scope document in docs/scope/, the architecture specs in docs/specs/, and the AGENTS.md context file all persist between sessions. When a new session starts, the agent reads those files from disk and picks up where the previous session left off.

This has a cost: each skill suggests running /clear at handoffs between phases, because reading fresh from disk is cheaper and more reliable than carrying a long accumulated chat context. The README notes that long chats pile up cost as well as context noise. For a team, the same file-based state means multiple engineers can work on the same feature loop as long as they commit the state files to the repository.

The workflow separates concerns between load-bearing design decisions (which /architect writes as specs with acceptance criteria) and behavioral correctness (which /check verify and /test check). The spec's acceptance criteria are the contract; every later step traces back to it. /develop checks that contract coverage before building, and at Beta and GA depth, /architect recommends running an independent cross-model critic over the spec to find gaps the design conversation never settled.

Workflow Depth Levels: Prototype Through GA

At the end of a /scope run, the engineer picks a workflow depth for the project. This depth controls how much checking follows each /develop step. The four levels are:

- Prototype: just /develop, self-checked. For throwaway work. - Alpha: adds /check verify (run the real app) after /develop. - Beta: adds /test (write a test suite) after /check verify. - GA: adds a fresh-model /check review and /document after /test.

The depth is a suggested checking tail, not a locked track. The engineer can run or skip any step and mark a feature done when they decide it is. The one requirement at every depth is that a load-bearing architectural decision gets written down with /architect rather than assumed. The README is direct on this point: the flag for an unratified Assumed spec does not block a feature from being marked done, but it is a standing reminder that the decision still owes ratification.

What This Package Does Not Cover

The package does not include an automated CI integration that runs the skills on every commit. Each skill is triggered manually by the engineer. There is no dashboard that shows which features are at which phase, beyond what the scope document in docs/scope/ contains.

The README notes that a hardening skill for systems-level failure mode analysis has been temporarily removed and will return as a system design specialization. Teams that need formal failure mode analysis will need to handle that outside the workflow. The workflow is also specific to the Agent Skills client ecosystem: teams using a custom AI coding agent that does not read SKILL.md files will not be able to use this package without adaptation.

Version 2.0.0 (as declared in package.json) has no GitHub releases, so there is no release changelog to consult when updating. The last push to the repository was on 2026-08-09.

Compared to Plain AGENTS.md Files

Many AI coding agent clients read a bare AGENTS.md (or CLAUDE.md, or .cursorrules) file that describes the project's stack, commands, and conventions. That file gives the agent context but imposes no phase structure and does not persist outputs between phases.

The difference in approach is that @jsmastery/skills adds a second layer on top: a sequence of skills that each read the files from the previous phase and write new files for the next one. The /audit skill writes AGENTS.md itself, so the context file is generated from the real codebase rather than written by hand. A team that already maintains a good AGENTS.md file and has a stable working style with their AI agent may not need the additional structure. A team that is onboarding new developers to AI-assisted coding, or that wants consistent architectural decisions written down as specs, will find the phase structure and the /architect spec gate useful.

Editorial conclusion

Engineers who want a structured, file-backed workflow for AI coding agents across Claude Code, Codex, or Cursor will find @jsmastery/skills provides useful phase boundaries and state persistence. It is not a useful install for teams who want a fully automatic, no-intervention pipeline: every phase requires the engineer to decide when to run the next skill and what input to give it. Before adopting it on an existing codebase, run /audit first so AGENTS.md reflects the real project structure, then read docs/workflow-guide.md to understand which files each skill writes and reads.

Frequently asked questions

Official sources

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