agentleFS
mazreanmazrean/agent-skills/skills/planning-wsh-improvements/SKILL.md

planning-wsh-improvements

Skill2 starsChanged 8 months agoMITView on GitHub

Analyzes a Web Speed Hackathon project, researches each improvement topic in depth, stores research as Agent Skills, and generates executable Claude Code commands for each optimization. Use when starting WSH optimization, creating an optimization roadmap, or generating executable improvement commands.

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before generating any plan, gather data:

    line 21
  2. Very specific:

    Create a skill directory at .claude/skills/wsh-{topic}/ for each improvement topic.

    line 51
  3. Distinctive:

    Create: when the topic has non-obvious details, pitfalls, or project-specific nuances

    line 54
  4. Distinctive:

    Create: when the optimization requires understanding of specific APIs, configs, or patterns

    line 55
  5. Distinctive:

    Skip: when the optimization is trivially simple (e.g., deleting one line)

    line 56
  6. Distinctive:

    If the project has oversized PNG images:

    line 74
  7. Very specific:

    Create a plan document at .claude/wsh-plan.md:

    line 94
  8. Distinctive:

    After generating all skills and commands:

    line 157

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Planning WSH Improvements

Analyzes a Web Speed Hackathon project, identifies performance bottlenecks, researches each improvement topic in depth, stores findings as reusable Agent Skills, and generates executable Claude Code commands. Every command references the relevant skill and includes mandatory Lighthouse score check followed by quick visual verification (curl + Playwright screenshot).

Use this skill when starting a WSH competition, creating an optimization plan, or when the user asks to generate improvement commands for a WSH project.

Supporting files:

  • COMMAND-TEMPLATE.md — Template and rules for generated commands
  • IMPROVEMENT-CATALOG.md — Known improvement patterns with priority/impact data
  • RESEARCH-SKILL-TEMPLATE.md — Template for generated research skills

Workflow

Step 1: Analyze the Project

Before generating any plan, gather data:

  1. Read package.json — Identify dependencies, build scripts, framework
  2. Read build config — webpack.config.*, vite.config.*, tsconfig.json
  3. Read docs/regulation.md or equivalent — Understand VRT and scoring rules
  4. Check server code — Look for artificial delays, N+1 queries, missing compression
  5. Check bundle size — Run npm run build if needed, inspect output
  6. Scan for known WSH traps — See IMPROVEMENT-CATALOG.md
  7. Run Lighthouse baseline — Measure and record scores for all scored pages before any changes
  8. Quick visual baseline — Confirm key pages load correctly via curl + screenshot before any changes

Step 2: Research & Generate Skills

For each identified improvement, conduct deep research and store the knowledge as an Agent Skill.

Research Process

For each improvement topic:

  1. Identify knowledge gaps — What does Claude need to know beyond general knowledge to implement this specific optimization correctly in this project?
  2. Research the topic using web search, documentation, and codebase analysis:
    • Official documentation for relevant tools/libraries
    • Known pitfalls and edge cases specific to this optimization
    • Compatibility with the project's tech stack (React version, bundler, etc.)
    • VRT implications — what visual changes this optimization might cause
    • Project-specific context — how the codebase uses the relevant code
  3. Synthesize findings into a focused Agent Skill

Skill Generation

Create a skill directory at .claude/skills/wsh-{topic}/ for each improvement topic. Follow the template in RESEARCH-SKILL-TEMPLATE.md.

When to create a skill vs. skip:

  • Create when the topic has non-obvious details, pitfalls, or project-specific nuances
  • Create when the optimization requires understanding of specific APIs, configs, or patterns
  • Skip when the optimization is trivially simple (e.g., deleting one line)

Skill naming: wsh-{topic} (e.g., wsh-avif-conversion, wsh-tree-shaking, wsh-preact-migration)

Skill content should include:

  • Specific techniques and their trade-offs
  • Code patterns and examples adapted to this project's stack
  • Known pitfalls and how to avoid them
  • VRT risk factors and mitigation strategies
  • References to official documentation

Do NOT include in the skill:

  • Generic knowledge Claude already has
  • Information that will be in the command itself (specific file paths, line numbers)
  • Time-sensitive information

Example: Research for Image Optimization

If the project has oversized PNG images:

  1. Research: AVIF vs WebP quality/size trade-offs, Sharp API for batch conversion, <picture> element with fallbacks, how the project's image pipeline works
  2. Generate skill at .claude/skills/wsh-image-optimization/SKILL.md:
    • AVIF encoding parameters for best size/quality balance
    • Sharp CLI commands for batch conversion
    • How to update image references in the project's component structure
    • VRT pitfalls: color profile shifts, transparency handling, quality thresholds

Step 3: Prioritize Improvements

Score each potential improvement:

  • Impact: Estimated Lighthouse score gain (from IMPROVEMENT-CATALOG.md)
  • Risk: VRT failure risk (Low / Medium / High)
  • Effort: Implementation complexity (Small / Medium / Large)

Sort by: Impact (descending) → Risk (ascending) → Effort (ascending)

Step 4: Generate the Plan Document

Create a plan document at .claude/wsh-plan.md:

# WSH Improvement Plan

Generated: {date}
Baseline VRT: PASS / FAIL
Estimated Total Impact: +{X} pts

## Lighthouse Baseline

| Page | FCP | SI | LCP | TBT | CLS | Score |
|------|-----|-----|-----|-----|-----|-------|
| / | {ms} | {ms} | {ms} | {ms} | {val} | {score} |
| {page} | ... | ... | ... | ... | ... | ... |

Total baseline: {sum} pts

## Improvements (Priority Order)

| # | Command | Skill | Category | Est. Impact | Risk | Effort |
|---|---------|-------|----------|-------------|------|--------|
| 1 | /wsh-001-{name} | wsh-{topic} | Bundle | +{X} pts | Low | Small |
| 2 | /wsh-002-{name} | wsh-{topic} | Image | +{X} pts | Medium | Medium |
| ... | ... | ... | ... | ... | ... | ... |

## Generated Skills

| Skill | Location | Covers |
|-------|----------|--------|
| wsh-{topic} | .claude/skills/wsh-{topic}/ | {brief description} |
| ... | ... | ... |

## Execution Notes

- Run commands in order (highest impact first)
- Each command references its skill for implementation knowledge
- Flow per command: Changes → Build → Lighthouse → Quick visual check → Commit → PR
- Assumes a dedicated improvement branch is already checked out
- If visual check fails, the command will guide you through resolution
- Each successful command produces a PR with Lighthouse results

Step 5: Generate Commands

For each improvement, create a command file at .claude/commands/wsh-{NNN}-{name}.md.

Command naming: wsh-{3-digit-number}-{short-name}

  • Number indicates priority order (001 = highest priority)
  • Short name describes the optimization

Every command MUST:

  1. Reference its skill — Include a line telling Claude to read the relevant skill for background knowledge
  2. Follow the template in COMMAND-TEMPLATE.md
  3. Have clear scope — Exactly ONE improvement per command
  4. Include concrete steps — Specific files, line numbers, changes
  5. Build verification — Must build successfully
  6. Lighthouse score check — Measure score impact on affected pages
  7. Quick visual check — curl for HTTP 200 + Playwright screenshot for visual spot-check (NOT full VRT/e2e)
  8. Commit & PR — Commit on verification pass, push, and create a PR with Lighthouse results

Step 6: Verify and Report

After generating all skills and commands:

  1. List generated skills: ls .claude/skills/wsh-*/SKILL.md
  2. List generated commands: ls .claude/commands/wsh-*.md
  3. Present the plan summary to the user
  4. Instruct: "Run /wsh-001-{name} to start the first improvement"

Important Rules

  • Never skip visual verification in any generated command — At minimum: curl HTTP 200 check + Playwright screenshot
  • Always run Lighthouse before visual check — Confirm score improvement, then confirm visual integrity
  • Do NOT run full e2e/VRT suites in generated commands — Too slow for iterative development; use curl + screenshot instead
  • Always commit and create PR after verification passes — Assumes improvement branch is already checked out
  • One improvement per command — Atomic and bisectable
  • Research before generating — Every non-trivial command should have a backing skill
  • Skills contain knowledge, commands contain actions — Keep this separation clean
  • Commands must be self-contained — Include all context needed (referencing the skill for background)
  • Include rollback guidance — If visual check fails, guide revert
  • Reference specific files and line numbers — No vague instructions
  • Adapt to the project — Read the actual codebase
  • Check regulation — Exclude rule-violating optimizations

Example Output Structure

.claude/
├── wsh-plan.md                              # The plan document
├── skills/
│   ├── wsh-production-build/
│   │   └── SKILL.md                         # Research: production mode, source maps, minification
│   ├── wsh-dependency-cleanup/
│   │   ├── SKILL.md                         # Research: bloated deps in this project
│   │   └── references/
│   │       └── REPLACEMENTS.md              # Detailed replacement strategies
│   ├── wsh-image-optimization/
│   │   └── SKILL.md                         # Research: AVIF conversion, lazy loading
│   └── wsh-runtime-css-removal/
│       └── SKILL.md                         # Research: UnoCSS runtime → static CSS
├── commands/
│   ├── wsh-001-production-mode.md           # Command referencing wsh-production-build
│   ├── wsh-002-remove-ffmpeg.md             # Command referencing wsh-dependency-cleanup
│   ├── wsh-003-remove-iconify.md            # Command referencing wsh-dependency-cleanup
│   ├── wsh-004-avif-images.md               # Command referencing wsh-image-optimization
│   └── wsh-005-static-css.md               # Command referencing wsh-runtime-css-removal

Note: Multiple commands can reference the same skill (e.g., several dependency removals share one skill).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.