.agents

A version-controlled home for Claude Code configuration: slash commands, skills, and plugins. The repo is public because Claude Code installs plugins from a GitHub marketplace, not from a local working copy.

Installation

Add the marketplace once, then install whichever plugins you need:

/plugin marketplace add nikoheikkila/.agents
/plugin install alt-text-generator@nikoheikkila-agents
/plugin install tdd@nikoheikkila-agents

Installed plugins are pinned to a commit SHA, so a change pushed to this repo isn't picked up automatically. Update with:

/plugin marketplace update nikoheikkila-agents
/plugin install <name>@nikoheikkila-agents

Available Plugins

alt-text-generator

Generates screen-reader-compatible alt text for images.

• Skill generating-alt-text — invoke directly as /alt-text-generator:generating-alt-text for interactive use, or let it trigger automatically on prompts like "write alt text for this image" or "is this accessible for screen readers?"
• Agent alt-text-generator — a noninteractive subagent (no clarifying questions, no preamble) that reads an image and returns alt text, intended for use by other agents or automation rather than direct chat.

tdd

Skills for the Red-Green-Refactor test-driven development cycle:

• red — write a failing test first, driven from Gherkin/BDD feature files, before any implementation exists.
• green — implement the minimal code needed to make a failing test pass, without over-engineering.
• refactor — improve code quality and design once tests are green, without changing behaviour.

Invoke as /tdd:red, /tdd:green, /tdd:refactor, or let them trigger on natural mentions of starting a TDD cycle, making a test pass, or cleaning up passing code.

Commands

commands/reflect.md → /reflect — a post-session maintenance loop. It reviews the current session for friction and writes durable improvements back into the relevant repo: repo-wide instructions into AGENTS.md/CLAUDE.md, human-facing docs into README.md, and skill amendments under .claude/skills/ (or, when run inside this repo, under this repo's own skills//plugins/).

Vendored Skills

skills/accessibility, skills/performance, and skills/find-skills were installed with the Skills CLI from addyosmani/web-quality-skills and vercel-labs/skills, and are tracked in .skill-lock.json. They reach Claude Code via per-skill symlinks into ~/.claude/skills/.

Do not hand-edit these — a future npx skills update will overwrite local changes. To check for or pull updates:

npx skills check    # see which vendored skills have updates
npx skills update    # pull them, rewriting skills/ and .skill-lock.json
npx skills add <owner/repo@skill> -g -y   # install a new one globally

If a vendored skill needs a real change, either contribute it upstream or fork it into plugins/ under a different name so it becomes authored content instead.

Authoring a New Plugin

1. Create plugins/<name>/.claude-plugin/plugin.json with name, version, description, author.
2. Add an entry for it in the root .claude-plugin/marketplace.json (name, source: "./plugins/<name>", description).
3. Add content directories inside the plugin: skills/<skill-name>/SKILL.md, agents/<agent>.md, etc.

A plugin skill's frontmatter name must match its directory name, and it's invoked as <plugin>:<skill>. Skill frontmatter descriptions are written as trigger lists in third person ("Use when the user asks…") rather than summaries, so Claude Code can match them against a user's phrasing. Subagent frontmatter pins tools, model, skills, and effort explicitly, and delegates its substance to a skill rather than restating it. Agents meant for noninteractive use say so explicitly and forbid clarifying questions and preamble, since either would corrupt the caller's output.

Push and update the marketplace to make a plugin change visible (see Install above).

Conventions

• Commit messages follow Conventional Commits (feat:, docs:, chore:).
• See CLAUDE.md for the fuller set of authoring rules Claude Code itself follows when editing this repository.