skills: Instructions file for Claude Code

CLAUDE.md

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

What this repo is

A Claude Code plugin marketplace (defined in .claude-plugin/marketplace.json) hosting:

• jidoka/ - the jidoka dev-workflow plugin for Claude Code (agents, skills, hooks), authored under src/ and rendered (see "One source, two renders" below). jidoka/evals/ is hand-written.
• utility-skills/ - standalone user-invocable skills with no agents or hooks. Each skill is a skills/<name>/SKILL.md file, optionally with bundled scripts/ and references/ beside it (as my-work has). Skills may declare required args: in frontmatter (YAML list with name, description, required). Current skills: teach-me, learn-it, spec-me, html-it, my-work.
• code-to-prd/ and clinical-lecture-brief/ - single-skill plugins (skills/<name>/SKILL.md with bundled resources such as scripts/ and references/), no agents or hooks.

claude plugin validate . checks the marketplace and its plugins load. The "test" is installing the plugin and exercising it: /plugin marketplace add wei6bin/skills, /plugin install jidoka@skills. The marketplace is added from GitHub, so a local edit is not live until it is merged to main and the plugin updated (claude plugin update jidoka@skills, or the marketplace's background auto-update on the next session start), then /reload-plugins. Installed contents land at ~/.claude/plugins/cache/skills/<plugin-name>/<commit-sha>/.

One source, two renders

src/ is the only place the jidoka plugin is edited. just build runs scripts/render.py (Python 3 with PyYAML) and rewrites every rendered path listed below; just check fails when the committed outputs are stale and is what CI runs (.github/workflows/render-check.yml).

• src/agents/<name>.md - one agent: a body plus frontmatter with name, description, tools (Claude tool names) and a role, which src/models.yaml resolves to a model (see "Model routing"). An optional model: map pins the Claude alias or the Copilot worker model when an agent must deviate from its role; say why in a comment. An optional claude: block adds Claude-only frontmatter keys (effort, which beats the role's, omitClaudeMd, is_background); it cannot set name, description, tools or model. Each agent is rendered twice: as the plugin's agent (jidoka/agents/<name>.md) and as the worker render (below). Text only one of them gets goes in a render section of the body: a line <!-- harness: claude --> (or worker) opens it, the next marker or <!-- harness: end --> closes it, and the renderer drops the sections that do not name the render (format in scripts/render.py). Today only impl-simplify has them, because the plugin's agent wraps Claude Code's built-in simplify skill while a worker on another harness, which has no such skill, gets the simplification rules. One file per agent; the renderer rejects a <name>.<suffix>.md.
• src/skills/<skill>/ - copied into jidoka/skills/. A skill has one render, read by the lead and by every herdr worker alike, so the renderer rejects a render section in one. A bundled script (a non-Markdown file starting #!) gets the hooks' one-line GENERATED comment; other files are copied byte for byte.
• The worker render: every agent is also written to jidoka/skills/herdr-crew/agents/<name>.md for herdr mode (see "Architecture"): the body plus the worker sections, under a flat frontmatter (role, tools, claude-model, claude-effort, copilot-model) that crew.sh reads. A worker without the jidoka plugin (Codex, Copilot CLI, Claude Code without the plugin) reads it as its instructions. src/skills/herdr-crew/agents/ must not exist; the renderer refuses it.
• src/hooks/hooks.json - the canonical afterFileEdit script list, rendered to Claude's PostToolUse (matcher Edit|Write|MultiEdit, ${CLAUDE_PLUGIN_ROOT}). src/hooks/*.sh are copied beside it.
• The agents and skills arrays of the jidoka entry in marketplace.json are rendered too: adding a file under src/agents/ or src/skills/ registers it on the next build.