CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This repository is a public collection of Claude Code skills and agents for software development workflows. There is no application to build: skills are Markdown (SKILL.md) with optional Bun/TypeScript helper scripts, and agents are single Markdown files.

For how Claude Code auto-loads skills, agents, rules, and memory, see .claude/references/claude-code-loading.md.

Repository structure

skills/              # one directory per published skill, each with a SKILL.md (plus optional scripts/ and references/)
agents/              # one Markdown file per agent
plugins/             # optional plugins beside the root one (e.g. to-code: a Claude Code mod plus a pi extension)
.claude-plugin/      # plugin.json and marketplace.json, so the repo installs as a Claude Code plugin
.claude/skills/      # skills internal to this repo, not published (e.g. writing-skills-update)
.claude/references/  # shared reference docs for authoring in this repo, plus pinned dependency submodules
.claude/rules/       # path-scoped authoring conventions for this repo
package.json         # Bun workspace root (workspaces: ["skills/*", "plugins/*"])
justfile             # symlink management for installing agents/ into ~/.claude/agents/

Skills under skills/ are the published collection and belong in the README.md table. Skills under .claude/skills/ are repo-internal tooling: they load automatically when working in this repository and are not listed in README.md.

Path-scoped rules

Conformance rules live in .claude/rules/ and auto-activate via paths: frontmatter when Claude edits matching files:

Authoring skills

• Invoke the skills-skill skill before creating or editing a skill.
• One directory per skill under skills/, containing a SKILL.md. Co-locate scripts/ and references/ inside the skill directory as needed.
• Frontmatter requires name and a description with trigger phrases so the skill activates reliably.
• Helper scripts use Bun + TypeScript. Run bun test to exercise their tests.

Authoring agents

• One Markdown file per agent under agents/. Restart Claude Code to load agent changes.
• Follow the frontmatter conventions in .claude/rules/agents.md.

Plugin packaging

The repository root is a Claude Code plugin (wyattjoh) and the marketplace (wyattjoh-skills), defined in .claude-plugin/. The marketplace also lists each optional plugin under plugins/, so installing wyattjoh never pulls them in. The root plugin relies on the default skills/ and agents/ directories, so new skills and agents ship without manifest edits. version is intentionally omitted so installs track the commit SHA. Run claude plugin validate . after touching either manifest.

Available scripts

Documentation

Update README.md whenever a skill or agent is added, removed, or renamed, so the agents and skills tables match the actual contents of agents/ and skills/.

Dependency References

Upstream repositories are registered as pinned git submodules under .claude/references/. They are for read-only reference only; do not edit files inside these paths.

The Effect repository is vendored twice because this repository uses two incompatible major versions. The Effect references are documentation snapshots. effect supplies v3 source for the unchanged workspaces, clean-storage, linked-docs, mermaid, and reference-submodules scripts; effect-v4 tracks the exact v4 release candidate documented by the effect-ts skill. Migrated runtime scripts target the current Alchemy-compatible stable release separately from that documentation corpus. For script API changes, use the skill's package manifest and matching installed Effect source. The v4 checkout also carries upstream MIGRATION.md, migration/, LLMS.md, and ai-docs/ directories that the v3 checkout does not.

The alchemy and effect-ts skills must always target the same Effect release. The source of truth is upstream alchemy's exact pin (overrides.effect in its pnpm-workspace.yaml), which skills/alchemy/scripts/build-skill.ts records as source.effectVersion in skills/alchemy/references/manifest.json. skills/alchemy/scripts/effect-version.test.ts fails unless every Effect v4 version in skills/effect-ts/ and the effect-v4 submodule tag match it, so after regenerating the alchemy corpus, bump the effect-ts skill and the effect-v4 submodule together in the same change.

To populate locally after a fresh clone:

git submodule sync
git submodule update --init --depth 1

Conventions

• Use Conventional Commits: <type>[scope]: <description>.
• Never use em dashes in written output, including comments, commit messages, and docs. Use commas, parentheses, or separate sentences instead.