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.
In this repository29 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- building-lit-componentsSkill
- building-static-site-rss-feedsSkill
- building-templ-componentsSkill
- checking-wsh-vrtSkill
- committing-codeSkill
- creating-agent-skillsSkill
- creating-test-casesSkill
- deploying-with-isucon-ansibleSkill
- designing-isucon-architectureSkill
- frontend-designSkill
- operating-isucon-servers-via-sshSkill
- porting-isucon-rust-to-goSkill
- releasing-zig-with-goreleaserSkill
- running-isucon-as-an-agentSkill
- sharing-sockets-with-so-reuseport-in-zigSkill
- tuning-isucon-linux-and-nginxSkill
- using-go-tool-directiveSkill
- using-grafana-mcpSkill
- using-unocss-with-templSkill
- winning-isuconSkill
- winning-web-speed-hackathonSkill
- writing-feature-specSkill
- writing-implementation-tasksSkill
- writing-isucon-arch-subagent-tasksSkill
- writing-project-constitutionSkill
- writing-technical-designSkill
- writing-zig-cli-toolsSkill
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
- Distinctive: line 21
Before generating any plan, gather data:
- Very specific: line 51
Create a skill directory at .claude/skills/wsh-{topic}/ for each improvement topic.
- Distinctive: line 54
Create: when the topic has non-obvious details, pitfalls, or project-specific nuances
- Distinctive: line 55
Create: when the optimization requires understanding of specific APIs, configs, or patterns
- Distinctive: line 56
Skip: when the optimization is trivially simple (e.g., deleting one line)
- Distinctive: line 74
If the project has oversized PNG images:
- Very specific: line 94
Create a plan document at .claude/wsh-plan.md:
- Distinctive: line 157
After generating all skills and commands:
≈ “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.
Files
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:
- Read
package.json— Identify dependencies, build scripts, framework - Read build config —
webpack.config.*,vite.config.*,tsconfig.json - Read
docs/regulation.mdor equivalent — Understand VRT and scoring rules - Check server code — Look for artificial delays, N+1 queries, missing compression
- Check bundle size — Run
npm run buildif needed, inspect output - Scan for known WSH traps — See IMPROVEMENT-CATALOG.md
- Run Lighthouse baseline — Measure and record scores for all scored pages before any changes
- 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:
- Identify knowledge gaps — What does Claude need to know beyond general knowledge to implement this specific optimization correctly in this project?
- 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
- 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:
- Research: AVIF vs WebP quality/size trade-offs, Sharp API for batch conversion,
<picture>element with fallbacks, how the project's image pipeline works - 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 resultsStep 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:
- Reference its skill — Include a line telling Claude to read the relevant skill for background knowledge
- Follow the template in COMMAND-TEMPLATE.md
- Have clear scope — Exactly ONE improvement per command
- Include concrete steps — Specific files, line numbers, changes
- Build verification — Must build successfully
- Lighthouse score check — Measure score impact on affected pages
- Quick visual check — curl for HTTP 200 + Playwright screenshot for visual spot-check (NOT full VRT/e2e)
- 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:
- List generated skills:
ls .claude/skills/wsh-*/SKILL.md - List generated commands:
ls .claude/commands/wsh-*.md - Present the plan summary to the user
- 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-removalNote: Multiple commands can reference the same skill (e.g., several dependency removals share one skill).
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
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.

