CLAUDE.md

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

This repo is two things: the canonical skill/hook/bootstrap home, and the source of the public storefront store.mazzeleczzare.com (site/). Treat site/ as a deployed public surface (HIGH posture): CI on main deploys it.

Storefront (site/ → store.mazzeleczzare.com)

• Astro (static output) on Cloudflare Workers, worker mazze93-skill-store; custom domain declared in site/wrangler.jsonc, assets served from dist/client.
• The catalogue is read at build time from .claude-plugin/skill-map.json — the single source of truth for plugin bundling and the store. Edit that file, never the generated artefacts; scripts/validate_marketplace.py fails CI on drift.
• cd site && npm run check = typecheck + build. Deploy is .github/workflows/verify.yml on main only — PRs build and typecheck but never deploy.
• Priced plugins need a checkout URL in skill-map.json; nothing here processes payment.
• http-cache-semantics is a locally patched build (site/vendor/http-cache-semantics/, wired via a file: dependency + $http-cache-semantics override). Don't "fix" the prerelease version or the override; read that directory's README first. npm run test:vendor fails if the installed package isn't the patched build.

Bootstrap (cold-start / new machine)

bash bootstrap/bootstrap.sh             # apply everything (idempotent)
bash bootstrap/bootstrap.sh --dry-run   # preview without writing

Prerequisites: jq, git, bash. Restart Claude Code after running.

Adding a skill

mkdir skills/<name>
# write skills/<name>/SKILL.md with frontmatter + content (see format below)
bash bootstrap/bootstrap.sh   # picks up the new symlink

Skill format

---
name: skill-name
description: One-line trigger description — shown in skill list, used for invocation matching.
---

# Content here

Skills can also be packaged as .skill files — ZIP archives containing SKILL.md plus an optional evals/ directory. The bootstrap does not auto-symlink .skill packages (it only globs directories); extract or install these manually.

Skills in this repo

Vendored skills

cloudflare, cloudflare-one, and web-perf are third-party content from cloudflare/skills, Apache-2.0, not written here. All eleven upstream skills were installed together on 2026-07-23; their combined listing entries cost ~1.2k resident tokens every session while the umbrella cloudflare skill already routed to all the same products.

Commit 42caf2b vendors them byte-exact as retrieved; the commit after it consolidates 10 → 2. Nothing was discarded — every satellite's SKILL.md body survives as a guide.md (or turnstile/spin.md) inside the umbrella's references/ tree, and the deep reference files sit beside the umbrella's own. Recover any original with git show 42caf2b:skills/<name>/SKILL.md.

These directories stay under Apache-2.0 — the repo's MIT license does not cover them. Each carries its own LICENSE and a NOTICE stating the changes made, as Apache-2.0 §4b requires. When editing them, update that NOTICE. Root NOTICE is the index.

Architecture

Symlink model

Everything is symlinked — nothing is copied:

• skills/<name>/ → ~/.claude/skills/<name> (install-skills.sh) — only for skills not already listed under a plugin in .claude-plugin/skill-map.json. A skill bundled into a marketplace plugin loads through the mazze93 marketplace instead; flat-symlinking it too double-registers it (Claude Code lists it both unscoped and as <plugin>:<skill>). install-skills.sh reads skill-map.json and skips those names.
• hooks/*.sh → ~/.claude/scripts/*.sh (install-hooks.sh)
• config/cc-statusline.sh → ~/.config/iterm2/cc-statusline.sh (install-skills.sh)

The bootstrap sub-scripts (bootstrap/lib/) handle their domains independently; bootstrap.sh just sequences them.

Hooks

Five hooks, each versioned in comments. Two aren't described below: credential-guard.sh (PreToolUse on Bash, a fail-closed block on commands that print secrets) and claude-md-drift-on-start.sh:

claude-md-drift-on-start.sh (SessionStart, matcher: startup) — runs skills/claude-md-audit/scan.py on the project being opened. Silent when clean. On findings, injects them as context plus a one-line systemMessage. Flags only, never rewrites. Fails loud: a missing scanner or dependency shows a message instead of skipping silently.

The other three:

on-prompt.sh (UserPromptSubmit) — two tiers:

• Tier 1 (always): scoring classifier emits task type + token budget hint (plan/implement/refactor/debug/review/read/general)
• Tier 2 (conditional, skipped for low budget): memory injection (once per session per project, via /tmp/claude-ctx/ flag files) + git branch/dirty state for high-stakes tasks

on-session-end.sh (Stop) — session stats (tool calls and Edit/Write counts, taken from assistant tool_use blocks via jq), memory write-back nudge listing the session cwd's memory files, uncommitted/unpushed git warnings (jj-aware), and an open-INTENTS-row nudge. Emits a systemMessage JSON so Claude Code displays the summary. Does not read mem-map.conf (dropped in v5).

post-tool-use.sh (PostToolUse, matcher: Edit|Write) — lightweight grep-only antipattern scanner: innerHTML with non-literal RHS, Linux /home/ paths on macOS, SQL string interpolation. Emits systemMessage JSON on findings only.

statusline (cc-statusline.sh)

Single jq pass extracts cwd, context_window.used_tokens, context_window.max_tokens. Maps CWD → project key via REL="${CWD#$HOME/Code/}" case match. Project → skill hint abbreviations live in the HINTS associative array inside the script — update there when adding projects.

install-settings.sh writes the PostToolUse hook entry into ~/.claude/settings.json (surgically via jq, never overwrites existing config, backs up before mutating).