agentleFS
dikamilodikamilo/dx-workflow/CLAUDE.md

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…

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
  1. Very specific:

    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 …

    line 32

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 set disable-model-invocation: true and 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-references uses user-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 when completion criterion.
  • Shared references are pulled by invoking dx-references with a topic — never deep-link another skill's files. Add a reference to dx-references/references/ only when ≥2 skills use it; otherwise collocate it inside its one skill.
  • Anti-ceremony. Markdown only — no HTML, no sidecar *.yml state. No auto-chain: print the next command and stop. Derive, don't maintain — lists from ls, 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 -->

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.