agentleFS
Sign inStart free
ScaleDockHQScaleDockHQ/scaledock-skills/AGENTS.md

scaledock-skills

AGENTS.md1 starsChanged 31 days agoMITView on GitHub

This repo publishes agent skills: opinionated scaledock-* skills for ScaleDock projects, and neutral spec skills for open specifications. Consumers install them with npx skills add ScaleDockHQ/scaledock-skills. Follow CONTRIBUTING.md for the details. The package manager is pnpm, pinned in package.json. Node is the major in .node-version. One branch and one PR per chat or plan.

  • Commits and pushes

We split this AGENTS.md into the rules it gives an agent

9 rules. About 0 are common, 3 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Start new skills with cp -r template/skill skills/scaledock-<topic> or cp -r template/standard-skill skills/<spec-name>.

    line 33
  2. Very specific:

    Do not edit .agents/skills/ or skills-lock.json by hand.

    line 34
  3. Distinctive:

    Run git status first. If there are uncommitted changes you did not make, stop and ask.

    line 42
  4. Very specific:

    After the first push, open one draft PR with gh pr create --base main, and mark it ready once pnpm verify passes.

    line 45
  5. Distinctive:

    Every later request in the same chat or plan goes on the same branch and PR.

    line 46
  6. Very specific:

    Run pnpm verify before you say you are done.

    line 61
  7. Very specific:

    Never bypass minimumReleaseAge or trustPolicy in pnpm-workspace.yaml.

    line 62
  8. Very specific:

    Every override, allowBuilds entry and held-back version has a comment saying why.

    line 63
  9. Distinctive:

    Only the toolchain, formatting, git hooks, CI and repo-file parts of the standard apply.

    line 69

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 AGENTS.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
AGENTS.md

AGENTS.md

This repo publishes agent skills: opinionated scaledock-* skills for ScaleDock projects, and neutral spec skills for open specifications. Consumers install them with npx skills add ScaleDockHQ/scaledock-skills. Follow CONTRIBUTING.md for the details.

Commands

The package manager is pnpm, pinned in package.json. Node is the major in .node-version.

CommandWhat it does
pnpm installInstalls the dev tooling and the git hooks.
pnpm validateChecks every skill's frontmatter, versions, links, sources and README entry.
pnpm formatFormats the repo with oxfmt.
pnpm checkRuns format:check and validate.
pnpm verifyThe full gate. CI and the pre-push hook run it. Done means it passes.
pnpm sources:checkFetches every spec skill source; lists dead links and stale checked dates.
pnpm dlx skills …Runs the skills CLI, for example pnpm dlx skills add . --list.

Layout

  • skills/<name>/: published skills. Each has SKILL.md, README.md, metadata.json, and optional references/, scripts/ and assets/.
  • template/skill/ and template/standard-skill/: the starting points for opinionated and spec skills.
  • scripts/: the validator, the source checker and the prepare hook installer.
  • docs/decisions/: ADRs.
  • .agents/skills/ and skills-lock.json: skills installed into this repo. They are committed so every contributor gets them; never gitignore them.

Invariants

  1. Opinionated skills are named scaledock-<topic>. Spec skills set metadata.kind: standard and are named after the specification without a prefix (ADR 0003). The frontmatter name is kebab-case and matches the folder name.
  2. The description starts with what the skill does, because the install picker shows only its first 57 characters. Then it says when to use the skill. It is at most 1024 characters.
  3. SKILL.md stays concise: inputs, invariants, workflow, verify checklist and reference index. Long material goes in references/, scripts/ or assets/.
  4. metadata.version in SKILL.md and version in metadata.json are bumped together, following semver.
  5. Start new skills with cp -r template/skill skills/scaledock-<topic> or cp -r template/standard-skill skills/<spec-name>.
  6. Do not edit .agents/skills/ or skills-lock.json by hand. Manage them with pnpm dlx skills; the lock is what keeps installed skills out of npx skills add ScaleDockHQ/scaledock-skills.
  7. Spec skills are neutral: no ScaleDock or PermDock beyond author and the install source. Every rule comes from a listed source, and every source is pinned in metadata.json sources and the ## Sources section.
  8. Skills point to other skills by name and install command, never by relative link.

Agent workflow

One branch and one PR per chat or plan.

  1. Run git status first. If there are uncommitted changes you did not make, stop and ask.
  2. From main, run git fetch and create <type>/<short-topic> from origin/main. If you are already on this work's branch, keep using it.
  3. Make small conventional commits and push. commitlint enforces the header, with a limit of 72 characters.
  4. After the first push, open one draft PR with gh pr create --base main, and mark it ready once pnpm verify passes. The PR title is a conventional commit header.
  5. Every later request in the same chat or plan goes on the same branch and PR. Never open a second PR, never stack PRs, and never merge or push to main unless asked.

When you change X, also update Y

ChangeAlso update
A skill's contentIts metadata.version and metadata.json version, and its README.md
A new skillThe matching skills table in README.md
A skill's descriptionIts row in the README.md skills table
A spec skill's sourcemetadata.json sources and ## Sources in SKILL.md, with a new checked
A dependency or action versionThe catalog in pnpm-workspace.yaml, and the pre-release pins list below
A workflowKeep .github/zizmor.yml passing; use each action's latest release tag

Hard rules

  • Run pnpm verify before you say you are done.
  • Never bypass minimumReleaseAge or trustPolicy in pnpm-workspace.yaml.
  • Every override, allowBuilds entry and held-back version has a comment saying why.

Deviations

Deliberate differences from scaledock-repo-standard, each with an ADR:

  • Only the toolchain, formatting, git hooks, CI and repo-file parts of the standard apply. App surfaces, Turborepo, TypeScript, Knip, oxlint, Changesets and Vercel do not. See ADR 0001.

Pre-release pins

None.

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.

Reviews can't be read right now.

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.

Check your setup, free