ai-modules CLAUDE.md

CLAUDE.md

ai-modules is a meta-repository. It defines AI components — skills, agents, commands, hooks — and packages them as plugins. Here command means the legacy standalone command artefact the deployer can still install (for example a Claude slash-command file under commands/), not a shell command and not a skill that is merely slash-invocable. Treat every SKILL.md, plugin.json, and marketplace.json as a published artefact: edits propagate to every machine that re-runs make deploy.

What this repo is not

The shipped skills are the product, not the workflow. When a user asks you to apply one while editing this repo, confirm whether they mean to invoke it or edit its definition.

Layout

.claude-plugin/marketplace.json   # Claude marketplace registration
.agents/plugins/marketplace.json  # Codex marketplace registration
plugins/<plugin>/
  .claude-plugin/plugin.json      # Claude plugin metadata
  .codex-plugin/plugin.json       # Codex plugin metadata (uses "skills": "./skills/")
  README.md                       # plugin overview + skill list
  skills/<skill>/SKILL.md         # skill definition with YAML frontmatter
styles/                           # tracked output styles (repo-root; not a plugin component)
deployment/                       # deploy script + per-tool config
tests/                            # local-only regression harnesses (gitignored)
Makefile                          # task entry point
.markdownlint.jsonc               # markdown lint config (MD033 off — pseudo-XML is intentional)

Authoring conventions

• Use pseudo-XML inside skill prompts (<role>, <objective>, <policy>, <output_contract>). Reference: plugins/ai_dev/skills/ai_instruction_formatting/SKILL.md.
• Use positive, action-oriented language in skill prose and instructions. Reference: plugins/ai_dev/skills/ai_instruction_writing/SKILL.md.
• Write skill descriptions for both audiences. The description: frontmatter is read before the body is loaded by an LLM router and by users browsing skills. Serve both needs deliberately: give the user a precise compact summary of what the skill is about and how it differs from neighbors, then give the router keyword-rich Use when trigger contexts, prompt phrases, artefacts, file types, and invocation boundaries. Keep implementation workflow details in the body.
• Keep the toolchain to Make + shell + Markdown, with jq, git, and Python 3 as accepted standing dependencies. Add further languages, package managers, or build steps only when the user explicitly asks for them.
• Match snake_case naming for skill and plugin directories.
• Name skills and agents by invocation mode and collision risk. A skill that is the only entry point for its capability keeps the ordinary family-first name, even when it delegates to agents (wiki_fix). Use <family>_auto_<rest> for an agent-delegating automation skill when it needs to sit beside a classical/manual skill with the same capability or subset (task_auto_implement beside task_implement). A spawned agent leads with auto_ and ends with the family token (auto_<role>_<family>, e.g. auto_implementer_task or auto_shaper_wiki) and is not intended to be invoked by the user.
• Write deployment-agnostic cross-references. Reference sibling artefacts by name (auto_shaper_wiki, format_markdown) rather than by plugin name, marketplace, or installed path.
• Bundle a skill's helper scripts inside the skill. A script that supports a skill lives at plugins/<plugin>/skills/<skill>/scripts/<name> and is referenced from its SKILL.md by the skill-relative path scripts/<name>. The plugin is the unit of distribution, so a script placed at the repo root or wired into the root Makefile is invisible to every deployment path except an in-place checkout. Add a repo-root scripts/ directory only for repo-wide tooling that belongs to no single skill, and only when explicitly asked.
• Author a skill-family rule once in the family's base skill. When a rule should govern a whole skill family (for example the task_* family), write it once in the base/hub skill so the front-end siblings inherit it through their <authority> reference instead of each carrying a copy. Pair enforcement with the canonical rule rather than restating it: a maintenance sibling such as task_fix carries a surface-and-propose advisory that points back at the base rule.