Skip to content

CLAUDE.md

Latest commit

 

History

History
69 lines (48 loc) · 3.65 KB

CLAUDE.md

File metadata and controls

69 lines (48 loc) · 3.65 KB

CLAUDE.md

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

What This Is

WOMM Skills is a Claude Code plugin — a self-improving skill suite for building software with AI. It ships 8 skills across two categories (process + fork lifecycle) and a growing golden specs knowledge base. Designed to be forked and customized.

Repo Structure

worksonmymachine-skills/
├── .claude-plugin/marketplace.json   # Plugin manifest — lists all skills
├── skills/{skill-name}/SKILL.md      # Each skill is a directory with SKILL.md + optional references/
├── golden-specs/                     # Knowledge base — read directly from ~/.womm-skills/golden-specs/
├── docs/epics/                       # Epic specs (numbered by phase: 00-, 01-, 02-)
├── docs/ideas/                       # Deferred skill ideas
├── plan.md                           # Master plan: repo structure, skill list, phased build plan
└── epics.md                          # Epic tracker hub (status of all epics)

Skill Format

Each skill lives in skills/{skill-name}/ with:

  • SKILL.md — YAML frontmatter (name, description, metadata.version) + markdown instructions
  • references/ — optional directory for templates and reference material

The description field in frontmatter doubles as the trigger — it tells Claude when to invoke the skill. Write it like the description fields in marketing-skills (keyword-rich, mentions related skills by name).

Two Mechanisms: Skills vs Golden Specs

  • Skills are installed via Claude Code's plugin system (claude plugin install womm-skills@womm-skills). Cached, available everywhere. Reinstall when upstream adds new skills.
  • Golden specs are flat markdown files at ~/.womm-skills/golden-specs/, referenced by ~/.claude/CLAUDE.md. Read directly from disk — no reinstall needed. Write a new one and it's available in every project immediately.

This separation exists because the plugin system copies files to cache (designed for static suites), but golden specs need to grow over time.

Conventions

  • Repo location: ~/.womm-skills/ (clone destination)
  • Golden specs path: ~/.womm-skills/golden-specs/
  • Golden spec naming: SCREAMING_SNAKE_CASE.md (e.g., RAILS_AWS_TERRAFORM_CONFIGURATION.md)
  • Upstream remote: upstream (standard git convention)
  • Sync marker: .womm-upstream-sync in repo root
  • Fork metadata: womm-manifest.json (generated by fork-share)
  • Skills should stay under 500 lines; put longer reference material in references/

Adding a New Skill

  1. Create skills/{skill-name}/SKILL.md with frontmatter and workflow
  2. Add references/ directory if the skill needs templates
  3. Update .claude-plugin/marketplace.json to include the new skill path
  4. All skills should check that ~/.womm-skills/golden-specs/ is accessible and provide setup instructions if not

Epic and Planning Structure

  • epics.md is the master tracker — check here for current status of all work
  • Individual epics live in docs/epics/ with naming pattern {phase}-{name}.md
  • Deferred ideas live in docs/ideas/
  • Epic statuses: Done, In Progress, Ready, Backlog
  • Implementation ordering: Phase 0 (infrastructure) -> Phase 1 (core skills) -> Phase 2 (starter content)

The 8 Skills

Process (5): design-doc, epic-breakdown, implementation-plan, implement, golden-spec-create Fork lifecycle (3): about, upstream-sync, fork-share

Contribution Model

Fork-first. Users fork and customize rather than submitting PRs. The upstream-sync and fork-share skills handle staying current with upstream and sharing what changed.