Skills Repository

Agent Skills collection for Claude Code, following the agentskills.io spec.

Uses the skills CLI for validation.

Skill Format

Each skill lives in its own directory under skills/ and consists of:

skills/<skill-name>/
├── SKILL.md      # The skill itself (frontmatter + instructions)
└── README.md     # Development documentation (REQUIRED)

Skills may also bundle additional directories as needed:

• scripts/ — executable wrappers referenced from SKILL.md via ${CLAUDE_SKILL_DIR}/scripts/...
• themes/ / assets/ — stylesheets, templates, or other static files used by scripts
• references/ — deep-dive docs loaded on demand, not auto-included
• tests/ — optional post-install smoke tests (not run by pnpm test; provide a manual command in the skill's README so contributors and post-install users can verify the setup works)

SKILL.md

YAML frontmatter followed by markdown instructions:

---
name: skill-name
description: When to activate and what the skill covers.
globs: ["**/*.ts", "**/*.tsx"]
license: MIT
---

The markdown body contains patterns, rules, and examples that Claude follows when the skill is active.

README.md (required)

Every skill directory must contain a README.md with development documentation:

• Purpose and scope of the skill
• Skill tier (publishable/reusable vs project-specific)
• How the skill was tested and validated
• Provenance (where patterns originated)
• Known gaps and planned improvements

Validation

pnpm test        # runs: skills add . --list

This lists all discovered skills and exits non-zero if any skill fails to parse.

Digraph Rendering

If SKILL.md contains ```dot blocks:

1. Create diagrams/ directory in skill folder
2. Run .dev/scripts/render-digraphs.sh SKILL.md ./diagrams
3. Commit both .dot and .png files
4. Reference images in SKILL.md where helpful

Requires: brew install graphviz

Gates Over Rules

For important agent behaviors, always implement gates, not rules. (Reference)

• A rule is a guideline the agent can rationalize around. Rules live in CLAUDE.md or skill instructions and depend on the agent choosing to follow them.
• A gate is a hard stop with objective verification — enforced via hooks (PreToolUse/PostToolUse) where the agent cannot proceed without meeting a concrete, checkable condition.
• The test: Can you answer "Did I complete this?" without actually doing the work? If yes, it's a rule. If no, it's a gate.

When writing skills that include critical workflows (session teardown, credential handling, destructive operations), always design enforcement as gates via hooks — not just instructions the agent should follow. Even when the user casually says "add a rule for X," evaluate whether it should be a gate and implement accordingly.

Skill authors: If your skill includes a "MUST" or "NEVER" instruction, ask: is this enforced by a hook, or just written in prose? If prose-only, it's a rule and will eventually be violated. Convert critical MUSTs to gates.

Key Principles

1. Be concise — Only add what Claude doesn't already know
2. Progressive disclosure — Overview in SKILL.md, details in referenced files
3. Third person — "Processes files" not "I help you process files"
4. One level deep — Reference files directly from SKILL.md, avoid nesting
5. Use ${CLAUDE_SKILL_DIR} for bundled files — Never use relative paths (./scripts/, ./file.md) in SKILL.md. Use ${CLAUDE_SKILL_DIR}/scripts/foo.sh so agents can find scripts regardless of their working directory.
6. Use checklists — Multi-step workflows benefit from copy-paste checklists
7. Test across models — Haiku may need more guidance than Opus

Skill Composition

Skills can reference other skills by name in their instructions. Claude loads both skills when context matches — no formal import system, just mention by name.

Adding and Editing Skills

• Always use /writing-skills when planning, creating, editing, or reviewing skills
• Keep skills generic — no account-specific data, API keys, or personal identifiers
• Skills should be self-contained: a single SKILL.md should cover a coherent topic
• Keep README.md in sync — When adding, removing, or renaming skills, update the skills table in the root README.md
• Continuous improvement: after using a skill, note gaps and propose concrete improvements
• Installation: symlink from ~/.claude/skills/ to the skill directory

Versioning

Every skill MUST have a metadata.version field in its SKILL.md frontmatter.

When a skill is changed, increment its version (semver):

• Patch (x.y.Z): bug fixes, wording improvements, minor clarifications
• Minor (x.Y.0): new sections, new patterns, expanded coverage
• Major (X.0.0): structural reorganization, removed sections, breaking workflow changes

Pre-release graduation: Any bump strips pre-release suffixes. 1.0.0-beta.1 + minor = 1.1.0.

When any skill version is bumped, add a changeset:

pnpm add-changelog   # creates a timestamped file in .changeset/ — edit bump type and description

The changeset describes what changed and at what semver level:

• Skill patch → plugin patch changeset (at minimum)
• Skill minor → plugin minor changeset (at minimum)
• Skill major → plugin major changeset

How long a changeset should be

A headline line, plus at most one short paragraph. That is the whole entry.

**`pandoc`** — `md2kindle-epub.sh` no longer emits EPUBs without a title.

`dc:title` is required EPUB metadata, but `--title` was optional and its absence
produced a spec-invalid book silently. The script now derives a title from the
first H1 of the first input, falling back to the output filename.

Shape: bold backticked skill name, em dash, one sentence naming what changed. Then one paragraph saying what it is for. No headings, no bullet lists.

Why: a changeset is a release note, answering one question — does this release affect me? It is not a design document. The reasoning, the hazards, the measurements and the rejected alternatives belong in the skill's SKILL.md, README.md and references/, which is where someone hits them while working.

Three consequences that make this a rule rather than a preference:

• The changeset text is copied verbatim into CHANGELOG.md, and create-release.sh feeds that section straight to gh release create --notes-file. It is the public release announcement, not an internal note.
• A published changelog entry is immutable. A fact restated there is the one copy that can never be corrected when it drifts.
• Nobody reads six paragraphs to decide whether to upgrade.

Cut, do not compress. Removing detail is the point; packing it into denser sentences defeats it. If something feels too important to cut, that is a signal it belongs in the README — put it there and link, rather than keeping it here.

Changeset bumps: Block (required)

Every changeset that modifies a skill MUST include a <!-- bumps: --> HTML comment block with structured YAML listing affected skills and their bump types. This is parsed by bump-skill-versions.sh to automatically update each skill's metadata.version in its SKILL.md frontmatter.

The block is stripped from the rendered CHANGELOG by sync-versions.sh, which runs after changeset version in pnpm run version. It is not hidden by changesets itself — changelog-github copies the changeset summary verbatim, so without that strip the block renders into CHANGELOG.md and then into the published GitHub Release. (It did: entries up to 4.2.0 carried it visibly until 2026-08-12.) Keep writing the block in the changeset — it is load-bearing there.

---
"@eins78/agent-skills": minor
---

Add `lab-notes` skill — structured experiment management

<!--
bumps:
  skills:
    lab-notes: minor
-->

Multiple skills:

<!--
bumps:
  skills:
    dossier: patch
    bye: patch
-->

If two changesets bump the same skill differently, the highest bump wins (major > minor > patch). The bumps: block is extensible — agents: can be added alongside skills: in the future.

Exception — a brand-new pre-release skill is not listed. A skill added for the first time with a pre-release metadata.version (e.g. 0.1.0-alpha.1) ships at that authored version, so its changeset leaves it out of skills: (an empty list is fine). Listing it would strip the suffix on release — increment_semver supports only major/minor/patch, so 0.1.0-alpha.1 + minor becomes 0.2.0. The exception covers the first release only; later changes list the skill as usual.

Do NOT manually edit version numbers in package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json, or .cursor-plugin/plugin.json. These are managed by pnpm run version which syncs all files automatically. Skill versions in SKILL.md are bumped automatically from the bumps: block — do not manually edit those either.

Releasing

Automated (GitHub Actions)

Releases are automated via changesets/action@v2:

1. Merge a PR with changesets to main
2. The Action creates a "Version Packages" PR with version bumps, CHANGELOG updates, and per-skill marketplace entries
3. Review and merge the version PR
4. The Action creates git tags (v2.2.0 + lab-notes@1.1.0) and a GitHub Release

main requires signed commits, and that constrains the action's config. v2 pushes release commits and tags through the GitHub API, which signs them with GitHub's web-flow key so they show as Verified. Under v1 the bot pushed with the git CLI, producing an unsigned commit that left every release PR mergeStateStatus: BLOCKED — 4.3.0 had to be merged with --admin. So:

• Do not set push-with-git-cli: true. That reverts to the unsigned push.
• The token must come through the github-token input; v2 ignores the GITHUB_TOKEN environment variable.

Manual (fallback)

GITHUB_TOKEN=$(gh auth token) pnpm run version   # bumps skill versions, consumes changesets, syncs all metadata
pnpm run release   # runs version, commits, tags — then push with: git push --follow-tags

Two Changesets v3 behaviours worth knowing before you run these by hand:

• Node ^22.11 || ^24 || >=26 is required (declared in engines). Node 20 no longer works.
• changeset version exits 1 when there are no pending changesets, where v2 exited 0 silently. pnpm run version chains with &&, so on an empty run it stops there and sync-versions.sh never executes. That is only a local-run surprise — the Action invokes the version script solely when changesets exist.

Validation

pnpm run validate  # checks all SKILL.md frontmatter (name, version, license, README)

Skill Name Stylization

When referencing skill names in prose (changelogs, PR descriptions, commit messages, documentation):

• Use backticks: lab-notes, dossier, bye
• Do NOT prefix with slash: lab-notes not /lab-notes
• The slash prefix is for invocation in chat (/lab-notes), not for naming in docs

Commit Conventions

Follow the existing commit style: <skill-name>: <description> for skill changes, plain descriptions for repo-level changes.