alexmskills: Instructions file for Claude Code

alexmskills

A public Claude Code plugin marketplace of reusable, self-improving skills and agents. Each skill is an independently versioned plugin. This file is the project's working memory; the README is the public front door.

Layout

.claude-plugin/marketplace.json   # the catalog — every plugin + its source/version
plugins/<name>/                   # one directory per plugin
  .claude-plugin/plugin.json      #   manifest (name, version, author, …)
  skills/<skill>/SKILL.md         #   one or more skills
  agents/<agent>.md               #   subagents (review-agents, dev-crew)
  hooks/hooks.json                #   plugin-shipped hooks (evolving-claude-md)
docs/                             # Antora component → published at alexmond.org/alexmskills
scripts/validate-marketplace.sh   # jq-based validator (also run in CI)
Makefile                          # validate / list / bump helpers
.claude/                          # per-plugin state (mindmap, prompt-coach, skill-linter)

Catalog (see README for descriptions)

evolving-claude-md, memory-hygiene, dev-crew, brainstorm-panel, learn-on-failure, roles, prompt-coach (self-learning) · implement-issue, maven-quality, security-audit, screenshot-tour, progress-channel, ticket-triage, context-bar, usage-bar (workflow) · review-agents (review) · research-sweep (research) · skill-linter (self-learning). Beta (-beta suffix): tune-repo-beta, systemic-fix-beta.

Conventions

• One skill = one plugin, unless skills are tightly coupled (then bundle + version them together, like maven-quality). This is what makes per-skill versioning possible at all.
• Every plugin.json carries the same metadata shape: name, description, version (semver), author (Alex Mondshain / [email protected]), homepage, repository, license: MIT, keywords. The name MUST match its marketplace.json entry.
• Bump versions with make bump PLUGIN=<n> VERSION=<x.y.z> so plugin.json and marketplace.json never drift. Validate with claude plugin tag --dry-run plugins/<n>.
• Run make validate before committing. CI runs it too.
• Skills must be project-agnostic. No hardcoded absolute paths, usernames, or repo names — these are pulled FROM other repos and generalized; keep them that way.
• Docs are part of "done": a new plugin needs a docs/modules/ROOT/pages/<n>.adoc page, a nav.adoc entry and a row on index.adoc; every version bump gets a CHANGELOG.md entry (grouped by date, tagged with plugin + version). make validate enforces all three — it was a convention until the landing page drifted four plugins behind the catalog.
• Plugin naming: orchestrators are <scope>-<team-noun>, the team-noun encoding coordination (crew = handoff/deliver, panel = debate/decide, sweep = fan-out/discover); other skills are descriptive kebab-case, verb-first for actions, ≤3 words, no redundant qualifiers.
• Role naming: a role is named for the persona (a noun — who they are), never the task (a verb — what they do), so it reads right seated solo, in a crew, on a panel, or in a sweep. Coverage roles use <dimension>-scout. Role names are shared across orchestrators (one skeptic, one architect).
• Never push or cut release tags without explicit user confirmation.
• Attribution: all plugins are original work by the author (MIT, per plugin.json author); the roles-plugin personas credit @nahidulislam404's prompt thread as inspiration. This is a public-repo provenance note; don't drop it in a cleanup.