Surface — PM Skill Generator

A Claude Code skill that reads any local repository, understands its design system, and creates 3 PM workflow skills tailored to that specific project. Run it once per project. From that point, PMs can make content and visual changes safely — with design enforcement, build verification, and clean PRs — without writing a single line of code.

---

What It Creates

Three skill files, generated specifically for your repo:

Skill	What it does
pm-design	Reads your repo's actual colors, fonts, and spacing. Before every PM edit, checks the request against your design system. After the edit, runs the dev server so the PM can visually confirm the change before it goes anywhere.
pm-abtest	After every PM change, silently runs the build and diffs the files. Flags anything that changed beyond what the PM intended. No questions asked unless something is unexpected.
pm-submit	Reads git history to match your branch naming convention, creates a pm/ branch, commits with PM add: [description], pushes, and opens a PR for developer review.

---

PM Personification

All 3 generated skills only activate when the user explicitly identifies as a PM using one of these exact phrases:

• "I am a PM"
• "I'm a PM"
• "As a PM"

No inference. No guessing. If the exact phrase isn't present, the skills stay completely silent. Regular developer workflows are completely unaffected.

---

Requirements

Before you start, make sure you have:

• Claude Code installed
• git installed
• gh CLI installed — used by pm-submit to create PRs

  brew install gh
  gh auth login

---

Setup

Step 1 — Clone Surface

git clone https://github.com/your-ai-buddy/surface
cd surface

Step 2 — Open in Claude Code

claude

This opens Claude Code in the surface directory. The generator skill is now available.

---

Generating Skills for a Repo

Step 3 — Run the generator

Say to Claude:

"Generate PM skills for /path/to/your-project"

Claude will silently read the target repo:

• package.json — framework, build command, dev command
• tailwind.config.* — color palette, spacing, typography
• CSS files — custom properties and design tokens
• Component files — patterns, naming, structure
• Git history — branch naming convention

Step 4 — Review each skill one at a time

Claude shows each generated skill and asks for your approval before moving to the next. You can request changes at each step — nothing is written until you say yes.

Shows pm-design → you approve or tweak
        ↓
Shows pm-abtest → you approve or tweak
        ↓
Shows pm-submit → you approve or tweak
        ↓
Creates .claude/skills/ in your repo and writes all 3 files

Step 5 — Done

Your repo now has 3 PM skills created:

your-project/
  .claude/
    skills/
      pm-design/SKILL.md
      pm-abtest/SKILL.md
      pm-submit/SKILL.md

---

PM Workflow (day-to-day)

Once the skills are created in a repo, here's how a PM uses them:

Step 1 — Open the project in Claude Code

cd your-project
claude

Step 2 — Identify as a PM

"I am a PM. I want to change the hero headline to 'Ship faster, together'."

Step 3 — pm-design kicks in

• Checks the request against the design system
• Makes the change
• Runs the dev server and gives the PM a preview URL
• Asks: "Does this look right?" via an interactive prompt
• PM confirms or requests adjustments

Step 4 — pm-abtest runs automatically

• Runs the build
• Diffs the files against what was changed
• Reports clean or flags unexpected side effects
• No questions unless something is wrong

Step 5 — pm-submit handles the PR

• Shows what changed and proposes a commit message: PM add: updated hero headline
• PM confirms or adjusts the wording
• Creates a pm/updated-hero-headline branch (following the repo's naming convention)
• Commits, pushes, opens a PR with a structured body
• Tells the PM: "Done! Here's your change request: [PR link]"

Rollback

If the PM wants to undo a change:

"Undo my last change"

• If the PR is still open → closes it and deletes the branch
• If the PR is already merged → creates a revert PR for developer approval

---

How the Design System is Detected

The generator uses a fallback chain to extract design values:

1. tailwind.config.* → full color palette, spacing scale, font sizes (Tailwind v3)
2. No config file (Tailwind v4 or plain CSS) → scans all component files for classes actually used
3. CSS custom properties (--color-*, --font-*, --space-*) in .css / .scss files
4. Direct inspection of 2–3 component files for patterns

Supports: Tailwind CSS, CSS Modules, plain CSS, SCSS.

---

Branch Naming

pm-submit reads the repo's git history and matches your existing convention:

Repo uses	PM branch becomes
feature/add-login	pm/add-login
fix/header-spacing	pm/header-spacing
No history found	pm/short-kebab-description

Always prefixed with pm/ so PM branches are instantly identifiable in GitHub.

---

Commit and PR Format

Every PM commit follows this format — no exceptions:

PM add: [short description]

PRs are created with:

• Title: PM add: [description]
• Label: content-change
• Body: What changed, requested by PM, review notes (content only, verify desktop + mobile)