dx-workflow
CLAUDE.md8 starsChanged 4 months agoMITView on GitHub
This repo authors the dx- skill set. DESIGN.md is the source of truth for behavior; this file orients anyone working on the skills. (It is not installed with the skills — each skill ships standalone via skills.sh. Target projects get only a one-line dx- pointer from dx-init; the never-auto-rollback principle lives in the skills themselves.) Adding, removing, or significantly changing a skill (behavior, invocation, reads/writes, Next: output) is not done until docs/ reflects it — update docs/reference/skills.md and any tutorial/explanation…
In this repository21 other files it gives its agents.
- dx-archiveSkill
- dx-brainstormSkill
- dx-diagnoseSkill
- dx-distillSkill
- dx-domain-discoverSkill
- dx-domainSkill
- dx-frameSkill
- dx-implementSkill
- dx-initSkill
- dx-lessonSkill
- dx-newSkill
- dx-planSkill
- dx-refactor-discoverSkill
- dx-referencesSkill
- dx-researchSkill
- dx-reviewSkill
- dx-review-triageSkill
- dx-roadmapSkill
- dx-standards-discoverSkill
- dx-standards-updateSkill
- dx-tddSkill
The file
We split this CLAUDE.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 32
Run npm run lint:skills after any edit under skills/dx-* — it's the same check CI's gate job runs, so catch it locally before opening the …
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
dx — maintainer orientation
This repo authors the dx- skill set. DESIGN.md is the source of truth for behavior; this file orients anyone working on the skills. (It is not installed with the skills — each skill ships standalone via skills.sh. Target projects get only a one-line dx- pointer from dx-init; the never-auto-rollback principle lives in the skills themselves.)
Layout
skills/
├── dx-references/ # loader (user-invocable:false) + references/*.md (shared docs)
└── dx-<skill>/SKILL.md # one directory per skill
DESIGN.md # the design spec — authority
package.json # install-skills / list-skills scripts (npx skills)Authoring rules (the house style)
- Frontmatter.
name: dx-<x>. User-invoked skills setdisable-model-invocation: trueand get a terse human-facing description (no trigger lists → zero context load). The two model-invoked skills —dx-diagnose,dx-domain— omit that flag and keep rich trigger phrasing. The utility skills other skills call by name —dx-new,dx-archive,dx-lesson,dx-standards-update— also omit it but keep terse human-facing descriptions (no trigger lists).dx-referencesusesuser-invocable: false(hidden from the/menu, still model-reachable). - Body. Short and principle-first. Leading words that recruit pretrained concepts (tight, red-capable, tracer bullet, deep module). Apply the no-op test: delete any sentence the model already obeys. Multi-step skills carry a
Done whencompletion criterion. - Shared references are pulled by invoking
dx-referenceswith a topic — never deep-link another skill's files. Add a reference todx-references/references/only when ≥2 skills use it; otherwise collocate it inside its one skill. - Anti-ceremony. Markdown only — no HTML, no sidecar
*.ymlstate. No auto-chain: print the next command and stop. Derive, don't maintain — lists fromls, status from frontmatter, effort progress from child changes.
Keep docs in sync
Adding, removing, or significantly changing a skill (behavior, invocation, reads/writes, Next: output) is not
done until docs/ reflects it — update docs/reference/skills.md and any tutorial/explanation page that
names the skill, in the same change. A new capability also gets a tutorial; a new workflow idea also gets an
explanation page. Use the documentation skill for all of it. A skill diff without a matching docs diff is incomplete.
Adding or removing a skill directory under skills/ also means adding or removing its entry in
skills.sh.json (under the right groupings entry, or notGrouped if none fits), in the same change.
Run npm run lint:skills after any edit under skills/dx-* — it's the same check CI's gate job runs, so catch it locally before opening the PR.
Versioning
Any PR touching skills/** must carry a changeset per change/slice it contains — run npx changeset before opening the PR (pick the bump type, write a one-line summary; it drops a file under .changeset/). Changes to context/, docs/, DESIGN.md, or other non-skills/ paths don't need one.
One PR, multiple slices. CI's gate job only checks that some .changeset/*.md exists, not that every slice is covered — on a multi-change branch it's satisfied the moment the first slice adds one, even if a later slice then touches skills/** uncovered. Before opening the PR, walk every child change (context/changes/, context/archive/<date>-*/) individually and confirm each one whose diff touches skills/** is described in its own changeset.
Merging to main runs the release job, which opens/updates a "Version Packages" PR bumping package.json and generating CHANGELOG.md; merging that PR is the actual version release. Turning the gate job into a required branch-protection check is a manual follow-up in GitHub Settings, not something this workflow configures.
See DESIGN.md §4 for the two-level model (effort ⊃ change) and the full skill lifecycle/entry shapes.
<!-- dx:workflow:start -->This project uses the dx- SDLC framework; workflow state lives under context/.
<!-- dx:workflow:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

