sreenivasanac · rohan-tessl · Apr 8, 2026
diff --git a/skills/mgrep/SKILL.md b/skills/mgrep/SKILL.md
@@ -1,35 +1,34 @@
 ---
 name: mgrep
-description: A semantic grep-like search tool for your local files. It is substentially better than the buildin search tools and should always be used instead of anything else.
+description: "Semantic search tool for local files using natural-language queries. Finds code, text, and concepts by meaning rather than literal string matching. Use when searching file contents, finding code patterns, locating functions or classes, grepping through a codebase, or answering questions about local files. Prefer over built-in grep for natural-language and conceptual searches."
 license: Apache 2.0
 ---
 
-## When to use this skill
+## When to Use
 
-Whenever you need to search your local files. Do not use grep, use this skill
-instead.
+Use `mgrep` instead of grep or ripgrep when searching local files. It understands natural language so queries can describe what you're looking for conceptually rather than matching exact strings.
 
-## How to use this skill
+## Usage
 
-Use `mgrep` to search your local files. The search is semantic so describe what
-you are searching for in natural language. The results is the file path and the
-line range of the match.
+```bash
+mgrep "<natural-language query>"                    # search current directory
+mgrep "<query>" <directory>                         # search specific directory
+mgrep -m <N> "<query>"                              # limit results to N matches
+```
+
+Results return file paths and line ranges of matches.
 
 ### Do
 
 ```bash
-mgrep "What code parsers are available?"  # search in the current directory
-mgrep "How are chunks defined?" src/models  # search in the src/models directory
-mgrep -m 10 "What is the maximum number of concurrent workers in the code parser?"  # limit the number of results to 10
+mgrep "What code parsers are available?"
+mgrep "How are chunks defined?" src/models
+mgrep -m 10 "What is the maximum number of concurrent workers in the code parser?"
 ```
 
 ### Don't
 
 ```bash
-mgrep "parser"  # The query is to imprecise, use a more specific query
-mgrep "How are chunks defined?" src/models --type python --context 3  # Too many unnecessary filters, remove them
+mgrep "parser"                      # too vague — describe what you need
+mgrep "query" --type python --context 3  # unnecessary filters — keep it simple
 ```
-
-## Keywords
-search, grep, files, local files, local search, local grep, local search, local
-grep, local search, local grep
diff --git a/skills/prompt-refiner/SKILL.md b/skills/prompt-refiner/SKILL.md
@@ -1,26 +1,48 @@
 ---
 name: prompt-refiner
-description: Improve prompts before sending them to get better results. Use when you want to refine a task description.
+description: "Restructure and improve AI prompts by adding clear goals, constraints, output format, and examples. Use when asked to refine a prompt, improve a task description, optimize a prompt for better results, or do prompt engineering."
 ---
 
 # Prompt Refiner
 
-## Instructions
+Transform rough task descriptions into clear, actionable prompts that produce better AI results.
 
-When the user wants to refine a prompt:
+## Refinement Workflow
 
-1. Ask for their draft prompt or task description
-2. Analyze it for:
-   - Clarity: Is the goal specific and measurable?
-   - Context: Does it include relevant background?
-   - Constraints: Are requirements and limitations stated?
-   - Examples: Would examples help clarify expectations?
-3. Suggest an improved version with explanations
-4. Offer to iterate if needed
+1. **Receive** the user's draft prompt or task description
+2. **Analyze** against these dimensions:
+   - Goal: Is the desired outcome specific and measurable?
+   - Context: Does it include relevant background the model needs?
+   - Constraints: Are requirements, limitations, and scope stated?
+   - Format: Is the expected output format specified?
+   - Examples: Would input/output examples clarify expectations?
+3. **Rewrite** the prompt applying the structured format below
+4. **Explain** what changed and why each improvement helps
+5. **Iterate** if the user wants further adjustments
 
-## Good Prompt Patterns
+## Structured Prompt Format
 
-- Start with the outcome: "Create a..." not "I want you to..."
-- Include acceptance criteria: "The result should..."
-- Specify format: "Return as JSON/markdown/code"
-- Mention constraints: "Must be compatible with...", "Should not modify..."
+Apply this structure to every refined prompt:
+
+```
+[Role/Context — only if domain expertise is needed]
+[Goal — one clear sentence stating the desired outcome]
+[Constraints — requirements, limitations, what to avoid]
+[Output format — specify structure: JSON, markdown, code, etc.]
+[Example — at least one input→output pair when helpful]
+```
+
+## Before/After Example
+
+**Before (vague):**
+> Write me a function that handles users
+
+**After (refined):**
+> Create a Python function `deactivate_user(user_id: int) -> bool` that:
+> - Looks up the user in the database by ID
+> - Sets their `is_active` field to False
+> - Returns True on success, False if user not found
+> - Raises `ValueError` if user_id is negative
+> - Do not delete the user record
+>
+> Return only the function with type hints and a docstring.
diff --git a/skills/rigorous-coding/SKILL.md b/skills/rigorous-coding/SKILL.md
@@ -1,9 +1,41 @@
 ---
 name: rigorous-coding
-description: Apply rigorous coding standards. Use when writing, implementing, or reviewing code.
+description: "Enforce rigorous coding standards by validating assumptions, verifying correctness, and handling edge cases. Use when writing new functions, implementing features, reviewing pull requests, debugging failures, or refactoring existing code to ensure robustness beyond the happy path."
 ---
 
-Do not write code before stating assumptions.
-Do not claim correctness you haven't verified.
-Do not handle only the happy path.
-Under what conditions does this work?
+# Rigorous Coding Standards
+
+Apply these standards to every code change — writing, reviewing, or refactoring.
+
+## Workflow
+
+1. **State assumptions** before writing code — document as comments what inputs are expected, what state is assumed, and what environment conditions must hold
+2. **Handle all paths** — identify failure modes, edge cases, and invalid inputs before implementing the happy path
+3. **Verify correctness** — test boundary conditions, confirm error handling works, and never claim code works without evidence
+4. **Question conditions** — for every function, answer: "Under what conditions does this work? Under what conditions does it fail?"
+
+## Checklist (apply to each function or change)
+
+- [ ] Assumptions documented as comments or preconditions
+- [ ] Input validation covers nulls, empty values, out-of-range, and wrong types
+- [ ] Error paths return meaningful messages (not silent failures)
+- [ ] Edge cases have explicit handling (empty collections, zero values, concurrent access)
+- [ ] No unchecked return values from external calls
+
+## Example
+
+```python
+# BAD — happy path only
+def get_user(user_id):
+    return db.query(f"SELECT * FROM users WHERE id = {user_id}")[0]
+
+# GOOD — assumptions stated, edges handled, correctness verified
+def get_user(user_id: int) -> User | None:
+    """Retrieve user by ID. Assumes DB connection is active."""
+    if not isinstance(user_id, int) or user_id <= 0:
+        raise ValueError(f"Invalid user_id: {user_id}")
+    results = db.query("SELECT * FROM users WHERE id = %s", (user_id,))
+    if not results:
+        return None
+    return User.from_row(results[0])
+```
diff --git a/skills/skill-creator/SKILL.md b/skills/skill-creator/SKILL.md
@@ -1,27 +1,11 @@
 ---
 name: skill-creator
-description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+description: "Create or update agent skills by generating SKILL.md frontmatter, writing structured markdown instructions, organizing bundled resources (scripts, references, assets), and validating skill structure. Use when asked to create a new skill, update an existing skill, build a SKILL.md file, or extend Claude with specialized knowledge or workflows."
 license: Complete terms in LICENSE.txt
 ---
 
 # Skill Creator
 
-This skill provides guidance for creating effective skills.
-
-## About Skills
-
-Skills are modular, self-contained packages that extend Claude's capabilities by providing
-specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
-domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
-equipped with procedural knowledge that no model can fully possess.
-
-### What Skills Provide
-
-1. Specialized workflows - Multi-step procedures for specific domains
-2. Tool integrations - Instructions for working with specific file formats or APIs
-3. Domain expertise - Company-specific knowledge, schemas, business logic
-4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
-
 ## Core Principles
 
 ### Concise is Key
@@ -66,60 +50,23 @@ Every SKILL.md consists of:
 
 #### Bundled Resources (optional)
 
-##### Scripts (`scripts/`)
-
-Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
-
-- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
-- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
-- **Benefits**: Token efficient, deterministic, may be executed without loading into context
-- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
-
-##### References (`references/`)
-
-Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
-
-- **When to include**: For documentation that Claude should reference while working
-- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
-- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
-- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
-- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
-- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
-
-##### Assets (`assets/`)
-
-Files not intended to be loaded into context, but rather used within the output Claude produces.
-
-- **When to include**: When the skill needs files that will be used in the final output
-- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
-- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
-- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
-
-#### What to Not Include in a Skill
-
-A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
-
-- README.md
-- INSTALLATION_GUIDE.md
-- QUICK_REFERENCE.md
-- CHANGELOG.md
-- etc.
-
-The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
-
-### Progressive Disclosure Design Principle
+| Resource | Directory | When to use | Example |
+|----------|-----------|-------------|---------|
+| Scripts | `scripts/` | Same code rewritten repeatedly or deterministic reliability needed | `scripts/rotate_pdf.py` |
+| References | `references/` | Documentation Claude should reference while working (schemas, APIs, policies) | `references/schema.md` |
+| Assets | `assets/` | Files used in output, not loaded into context (templates, images, fonts) | `assets/template/` |
 
-Skills use a three-level loading system to manage context efficiently:
+- Avoid duplication between SKILL.md and references — detailed content belongs in reference files, keep SKILL.md lean
+- For large references (>10k words), include grep search patterns in SKILL.md
+- Do NOT include README.md, CHANGELOG.md, or other auxiliary documentation — only files the agent needs to do the job
 
-1. **Metadata (name + description)** - Always in context (~100 words)
-2. **SKILL.md body** - When skill triggers (<5k words)
-3. **Bundled resources** - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
+### Progressive Disclosure
 
-#### Progressive Disclosure Patterns
+Skills load in three levels: **metadata** (always in context, ~100 words) → **SKILL.md body** (on trigger, <5k words) → **bundled resources** (as needed, unlimited).
 
-Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+Keep SKILL.md under 500 lines. When approaching this limit, split content into reference files and describe clearly when to read them.
 
-**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+**Key principle:** Keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details into separate reference files.
 
 **Pattern 1: High-level guide with references**
 

diff --git a/skills/web-design-guidelines/SKILL.md b/skills/web-design-guidelines/SKILL.md
@@ -1,36 +1,34 @@
 ---
 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".
-argument-hint: <file-or-pattern>
+description: "Review UI code for compliance with Web Interface Guidelines covering semantic HTML, keyboard navigation, color contrast, responsive layout, and interaction patterns. Use when asked to review UI code, check accessibility, audit design, review UX, or check a site against web best practices."
 ---
 
-# Web Interface Guidelines
+# Web Interface Guidelines Review
 
 Review files for compliance with Web Interface Guidelines.
 
-## How It Works
+## Workflow
 
-1. Fetch the latest guidelines from the source URL below
-2. Read the specified files (or prompt user for files/pattern)
-3. Check against all rules in the fetched guidelines
-4. Output findings in the terse `file:line` format
+1. **Fetch guidelines** — retrieve the latest rules before each review:
+   ```
+   https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
+   ```
+   Use WebFetch to retrieve. The fetched content contains all rules and the output format specification.
 
-## Guidelines Source
+2. **Identify files** — use the file or pattern argument provided by the user. If none specified, ask which files to review.
 
-Fetch fresh guidelines before each review:
+3. **Apply rules** — check every rule from the fetched guidelines against the specified files.
 
-```
-https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
-```
+4. **Report findings** — output in terse `file:line` format as specified in the guidelines.
 
-Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
+## Example Output
 
-## Usage
+```
+src/components/Button.tsx:12 — missing aria-label on interactive element
+src/pages/Home.tsx:45 — color contrast ratio below 4.5:1 on body text
+src/layout/Nav.tsx:8 — navigation not keyboard-accessible (no tabindex or focus management)
+```
 
-When a user provides a file or pattern argument:
-1. Fetch guidelines from the source URL above
-2. Read the specified files
-3. Apply all rules from the fetched guidelines
-4. Output findings using the format specified in the guidelines
+## Fallback
 
-If no files specified, ask the user which files to review.
+If the URL fetch fails, ask the user to provide the guidelines content manually or check the URL.