CLAUDE.md ยท diff
git:20260414.a348c3e to git:20260808.7dfb5c7
78 added, 50 removed. Audit A to A.
- # Claude Skills Repository
+ # CLAUDE.md
- A public collection of generic, reusable Claude Code skills. Skills here must work for any user in any project.
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
- ## Project Structure
+ ## What This Repo Is
+ A public collection of generic, reusable Claude Code skills, organised by job role. Skills here must work for any user in any project. There is no application code: the "product" is the `skills/` tree plus the installer that copies it into a user's `~/.claude/skills/`.
+
+ ## Commands
+
+ ```bash
+ # Validate every SKILL.md (frontmatter + 500-line limit). Run before committing.
+ python3 scripts/validate_skill.py
+
+ # Validate skills.json parses (what CI runs first)
+ python3 -c "import json; json.load(open('skills.json'))"
+
+ # Scaffold a new skill and auto-register it in skills.json
+ python3 scripts/init_skill.py <skill-name> --role <role> --description "..." --tags "a,b"
+
+ # Install locally to test the packaging path
+ bash scripts/install.sh --list
+ bash scripts/install.sh --role pm # global: ~/.claude/skills
+ bash scripts/install.sh --role pm --project # project: ./.claude/skills
+ bash scripts/install.sh --all
+ bash scripts/install.sh --update
+ bash scripts/install.sh --uninstall qa
```
- claude-skills/
- skills/ # Generic skills (each with SKILL.md)
- scripts/
- install.sh # User-facing installer
- .claude/
- skills/
- create-skill/ # Internal skill: Anthropic skill standard reference + creation guide
- sync-skills/ # Internal skill: fetch + genericize skills from other systems
- CLAUDE.md # This file (project instructions)
- README.md # Public-facing documentation
+
+ There is no test suite. `validate_skill.py` is the only checked gate, and it validates all skills at once. To check one skill, run the validator and grep its path.
+
+ ## Architecture
+
+ Three surfaces must agree, and nothing enforces the agreement automatically:
+
+ 1. `skills/` on disk. Two shapes only: `skills/by-role/<role>/<skill>/SKILL.md` and `skills/shared/<skill>/SKILL.md`. `install.sh` derives the source path from the registry key, so a skill in the wrong directory shape fails at install time, not at validation time.
+ 2. `skills.json` - the registry, and the real source of truth for installation. Keys are `<role>/<skill-name>` (shared skills use the literal key `shared/<skill-name>`). `install.sh` reads only this file to decide what exists, which roles are offered by `--list`, and what `--all` installs. **A skill folder that is not registered here is invisible to users.**
+ 3. `README.md` - the public skills table plus the "N skills across M roles" tagline. Purely manual, drifts silently.
+
+ `validate_skill.py` accepts the registry as an argument but never checks against it, so registry drift passes CI. Before finishing any skill work, reconcile all three:
+
+ ```bash
+ python3 -c "
+ import json,pathlib
+ reg=set(json.load(open('skills.json'))['skills'])
+ disk={('shared/'+p.parent.name) if p.parts[1]=='shared' else p.parent.parent.name+'/'+p.parent.name
+ for p in pathlib.Path('skills').rglob('SKILL.md')}
+ print('on disk, unregistered (invisible to install):', sorted(disk-reg))
+ print('registered, missing folder (install will error):', sorted(reg-disk))
+ "
```
- ## Rules for Skills in This Repo
+ Known current drift: several `marketing/*` and `shared/*` skills exist on disk but are unregistered, and the `content-creator/*` plus four `pm/*` entries are registered with no folder. Fix the reconciliation for any role you touch rather than adding to it.
- 1. **No personal content.** Replace names, domains, newsletter titles, project references with `[placeholder]` brackets.
- 2. **No project-specific paths or configs.** Skills must work when dropped into any `.claude/skills/` directory.
- 3. **Every skill follows Anthropic skill standard.** YAML frontmatter with `name` + `description`, markdown body under 500 lines, overflow in `references/` subdirectory.
- 4. **The `description` field is the trigger.** Put all "when to use" context there. Body is the instruction set.
- 5. **Each skill must include:** a workflow (step-by-step), anti-patterns, and a quality checklist.
- 6. **Placeholders to use:** `[your niche]`, `[your newsletter]`, `[your-domain]`, `[your topic]`, `[your name]`, `[your audience]`.
+ Adding a new role means adding it to `VALID_ROLES` in `scripts/init_skill.py` first. `install.sh` discovers roles dynamically from `skills.json`, so no installer change is needed.
- ## Skill Creation Standard (MANDATORY)
+ CI (`.github/workflows/validate.yml`) runs only on PRs touching `skills/**` or `skills.json`.
- **Always follow the Anthropic skill-creator guidelines when creating or updating any skill:**
- https://github.com/anthropics/skills/tree/main/skills/skill-creator
+ ## Required Reading
- The full process (do not skip steps):
- 1. Capture intent - understand what the skill should do and when it should trigger
- 2. Write the SKILL.md following the FIRAC body structure (Overview, Workflow, Anti-Patterns, Quality Checklist)
- 3. Create 2-3 realistic test prompts and run with-skill + baseline subagents in the same turn
- 4. Draft assertions while runs are in progress
- 5. Grade results and show user a qualitative comparison
- 6. Iterate on the skill based on feedback
- 7. Add reference files in `references/` for any domain-specific data the skill references but cannot include inline (benchmarks, templates, authority hierarchies, procedure maps)
- 8. Update SKILL.md to point to reference files with explicit guidance on when to read each one
+ `.claude/rules/prompt-writing.md` - the prompt-writing rubric (scored out of 100, target >95). Follow it when authoring or editing any skill description or body.
- ## When Adding a Skill
+ ## Internal Skills
- - Follow the Anthropic skill-creator process above (mandatory).
- - Scaffold with `python3 scripts/init_skill.py <name> --role <role>` - registers in `skills.json` automatically.
- - If adding a new role, add it to `VALID_ROLES` in `scripts/init_skill.py` first.
- - Read the source skill from the original project first.
- - Strip all personal/project references. Replace with placeholders.
- - Verify the skill works standalone - no dependencies on other skills or project-specific files.
- - Run `python3 scripts/validate_skill.py` before committing.
- - Update `README.md` skills table (skill count + role count in tagline, add role section).
+ - `.claude/skills/create-skill/` - the Anthropic skill standard reference and creation guide.
+ - `.claude/skills/sync-skills/` - fetch and genericize skills from another machine's projects, deduplicate against this repo, and update `skills.json` plus `README.md`.
- ## When Syncing from Another System
+ ## Rules for Skills in This Repo
- Use `/sync-skills` to fetch skills from another machine's projects. The skill handles:
- - Scanning all projects under a given root for `.claude/skills/` directories
- - Deduplicating against skills already in this repo
- - Genericizing content (stripping project-specific references)
- - Updating skills.json and README.md
+ 1. **No personal content.** Replace names, domains, newsletter titles, and project references with `[placeholder]` brackets. Standard placeholders: `[your niche]`, `[your newsletter]`, `[your-domain]`, `[your topic]`, `[your name]`, `[your audience]`.
+ 2. **No project-specific paths or configs.** A skill must work when dropped into any `.claude/skills/` directory, with no dependency on another skill or on a project file.
+ 3. **The `description` field is the trigger.** All "when to use" context goes there, not in the body. The body is the instruction set.
+ 4. **Body under 500 lines** (validator hard-fails past it). Overflow goes into a `references/` subdirectory, and `SKILL.md` must say explicitly when to read each reference file.
+ 5. **Every skill contains** a step-by-step workflow, anti-patterns, and a quality checklist.
+ ## Skill Creation Standard (MANDATORY)
+
+ Follow the Anthropic skill-creator guidelines: https://github.com/anthropics/skills/tree/main/skills/skill-creator
+
+ Do not skip steps:
+
+ 1. Capture intent - what the skill does and when it should trigger.
+ 2. Write `SKILL.md` with the FIRAC body structure (Overview, Workflow, Anti-Patterns, Quality Checklist).
+ 3. Create 2-3 realistic test prompts, then run with-skill and baseline subagents in the same turn.
+ 4. Draft assertions while the runs are in progress.
+ 5. Grade the results and show the user a qualitative comparison.
+ 6. Iterate based on feedback.
+ 7. Add `references/` files for domain data the skill needs but cannot hold inline (benchmarks, templates, authority hierarchies, procedure maps).
+ 8. Point `SKILL.md` at those reference files with explicit read-when guidance.
+
+ When importing a skill from another project, read the source skill first, then strip every personal and project reference before it lands here.
+
## Commit Conventions
- - Lowercase, imperative mood: `add linkedin-post skill`, `update install script`
- - Prefixes: add, update, remove, fix, sync
- - Short first line (under 72 chars)
+ Lowercase, imperative mood, under 72 characters: `add linkedin-post skill`, `update install script`. Prefixes: add, update, remove, fix, sync.