zhongwei/gh-jgardner04-skills-jgardner04-skills

Fork 0

Files

Zhongwei Li 42b20ade49 Initial commit

2025-11-30 08:25:55 +08:00

14 KiB

Raw Permalink Blame History

Claude Skills Examples

Real-world examples of well-designed skills across different complexity levels and use cases.

Simple Skills - Just SKILL.md, no scripts
Skills with Scripts - Including helper utilities
Complex Skills - Full-featured with references
Platform-Specific Skills - Optimized for one platform
Universal Skills - Work across all platforms

Simple Skills

Example 1: Commit Message Formatter

Use Case: Help developers write conventional commit messages

Structure:

commit-formatter/
└── SKILL.md

SKILL.md:

---
name: commit-formatter
description: Format git commit messages following Conventional Commits. Use when writing commits or reviewing commit history for proper formatting.
---

# Commit Message Formatter

Helps create well-formatted git commit messages following the Conventional Commits specification.

## When to Use

- Writing new commit messages
- Reviewing existing commits for proper format
- Teaching team members commit conventions
- Generating changelogs

## Commit Format

():

```

Types

feat: New feature for users
fix: Bug fix
docs: Documentation only changes
style: Code style changes (formatting, semicolons)
refactor: Code change that neither fixes a bug nor adds a feature
perf: Performance improvement
test: Adding or updating tests
chore: Maintenance tasks (deps, configs)
ci: CI/CD changes

Subject Line Rules

Use imperative mood ("add" not "added")
No period at the end
Keep under 50 characters
Lowercase (except proper nouns)

Body (Optional)

Wrap at 72 characters
Explain WHAT and WHY (not HOW)
Separate from subject with blank line

Footer (Optional)

Breaking changes: BREAKING CHANGE: <description>
Issue references: Closes #123, Fixes #456
Co-authors: Co-authored-by: Name <email>

Examples

Simple Feature

feat(auth): add OAuth2 Google login

Bug Fix with Body

fix(api): handle null user service response

The user service occasionally returns null when the user is not
found. This adds proper null checking and returns a 404 status.

Breaking Change

feat(api)!: redesign authentication endpoints

BREAKING CHANGE: The /auth endpoint now requires POST instead of GET.
All clients must be updated to send POST requests with JSON body
containing username and password fields.

Migration guide: https://docs.example.com/v2-migration

Closes #456

Multiple Issues

fix(ui): resolve button alignment in mobile view

Fixes several CSS issues affecting mobile users:
- Button text now wraps properly
- Icons align correctly with text
- Touch targets meet minimum 44px requirement

Fixes #789, #790, #791

Interactive Mode

Just tell me what you changed, and I'll help format it:

Example conversation:

You: "I added a new login page"
Me: "Was this a new feature or a fix?"
You: "New feature"
Me: "What component/area does this affect?"
You: "Authentication"
Me: "Here's your commit message: feat(auth): add login page"


**Why This Works**:
- Clear, actionable instructions
- Concrete examples for different scenarios
- Covers edge cases (breaking changes, multiple issues)
- Action-oriented description triggers automatic use
- No dependencies or scripts needed

---

### Example 2: JSON Formatter

**Use Case**: Format and validate JSON data

**Structure**:

json-formatter/ └── SKILL.md


**SKILL.md**:
```markdown
---
name: json-formatter
description: Format, validate, and pretty-print JSON data. Use when working with JSON files, API responses, or config files that need formatting or validation.
---

# JSON Formatter

Format and validate JSON data with helpful error messages.

## When to Use

- Format messy JSON
- Validate JSON syntax
- Compare JSON structures
- Convert between compact and pretty formats
- Debug JSON parsing errors

## Features

### 1. Pretty Printing

Transform compact JSON into readable format:

**Input**:
```json
{"name":"John","age":30,"city":"NYC"}

Output:

{
  "name": "John",
  "age": 30,
  "city": "NYC"
}

2. Validation

Check for common JSON errors:

Missing commas
Trailing commas
Unquoted keys
Single quotes instead of double quotes
Unescaped characters

3. Minification

Reduce JSON size for transmission:

Input:

{
  "users": [
    {
      "name": "John",
      "age": 30
    }
  ]
}

Output:

{"users":[{"name":"John","age":30}]}

4. Structure Analysis

Count objects, arrays, and primitives
Find deeply nested paths
Identify large values
Detect duplicate keys

Usage

Just paste or upload your JSON and tell me what you need:

"Format this JSON"
"Validate this JSON"
"Minify this JSON"
"What's wrong with this JSON?"
"Compare these two JSON files"

Common Fixes

Trailing Comma

❌ {"name": "John", "age": 30,} ✅ {"name": "John", "age": 30}

Single Quotes

❌ {'name': 'John'} ✅ {"name": "John"}

Unquoted Keys

❌ {name: "John"} ✅ {"name": "John"}

Missing Comma

❌ {"name": "John" "age": 30} ✅ {"name": "John", "age": 30}

Tips

Use JSON for configs (not YAML) when strict validation needed
Keep nesting under 5 levels for readability
Consider splitting large JSON files
Use consistent key naming (camelCase or snake_case)


---

## Skills with Scripts

### Example 3: API Response Validator

**Use Case**: Validate API responses against schemas

**Structure**:

api-validator/ ├── SKILL.md ├── scripts/ │ ├── init.py │ ├── validator.py │ └── schema_builder.py └── README.md


**SKILL.md**:
```markdown
---
name: api-validator
description: Validate API responses against JSON schemas with detailed error reports. Use PROACTIVELY when testing or debugging REST APIs.
tools: Bash, Read, Write
model: sonnet
---

# API Response Validator

Comprehensive validation for API responses.

## Features

- Validate against JSON Schema
- Auto-generate schemas from examples
- Test status codes, headers, body
- Performance metrics
- Security checks

## Usage

### Validate a Response

Validate this API response: { "status": 200, "body": {"user_id": 123, "name": "John"} }

Against schema: { "type": "object", "required": ["user_id", "name"], "properties": { "user_id": {"type": "integer"}, "name": {"type": "string"} } }


### Generate Schema

Generate a schema for this response: {"user_id": 123, "name": "John", "email": "john@example.com"}


### Batch Validation

Validate all responses in ./tests/responses/


## Scripts

This skill includes Python scripts for deterministic validation:

- `validator.py`: Core validation logic
- `schema_builder.py`: Generate schemas from examples

Run manually:
```bash
python scripts/validator.py response.json schema.json

See README.md for detailed script documentation.


**scripts/validator.py**:
```python
#!/usr/bin/env python3
"""Validate JSON against JSON Schema."""

import argparse
import json
import sys
from pathlib import Path
from typing import Any, Dict, List, Tuple


def validate_json(data: Dict[str, Any], schema: Dict[str, Any]) -> Tuple[bool, List[str]]:
    """Validate JSON data against schema.

    Returns:
        Tuple of (is_valid, error_messages)
    """
    errors = []

    # Check required fields
    if "required" in schema:
        for field in schema["required"]:
            if field not in data:
                errors.append(f"Missing required field: {field}")

    # Check field types
    if "properties" in schema:
        for field, field_schema in schema["properties"].items():
            if field in data:
                expected_type = field_schema.get("type")
                actual_value = data[field]

                if not check_type(actual_value, expected_type):
                    errors.append(
                        f"Field '{field}' has wrong type. "
                        f"Expected {expected_type}, got {type(actual_value).__name__}"
                    )

    return len(errors) == 0, errors


def check_type(value: Any, expected_type: str) -> bool:
    """Check if value matches expected JSON type."""
    type_map = {
        "string": str,
        "integer": int,
        "number": (int, float),
        "boolean": bool,
        "array": list,
        "object": dict,
        "null": type(None),
    }

    expected_python_type = type_map.get(expected_type)
    if expected_python_type is None:
        return True  # Unknown type, skip check

    return isinstance(value, expected_python_type)


def main() -> int:
    parser = argparse.ArgumentParser(description="Validate JSON against schema")
    parser.add_argument("data_file", type=Path, help="JSON data file")
    parser.add_argument("schema_file", type=Path, help="JSON schema file")

    args = parser.parse_args()

    # Load files
    try:
        data = json.loads(args.data_file.read_text())
        schema = json.loads(args.schema_file.read_text())
    except json.JSONDecodeError as e:
        print(f"Error: Invalid JSON - {e}", file=sys.stderr)
        return 1
    except Exception as e:
        print(f"Error: {e}", file=sys.stderr)
        return 1

    # Validate
    is_valid, errors = validate_json(data, schema)

    if is_valid:
        print("✅ Validation passed")
        return 0
    else:
        print("❌ Validation failed:")
        for error in errors:
            print(f"  - {error}")
        return 1


if __name__ == "__main__":
    sys.exit(main())

Why This Works:

Combines AI guidance with deterministic validation
Scripts provide precise, repeatable checks
Clear examples show usage patterns
Works across platforms (with network in Code, offline in API)

Complex Skills

Example 4: Database Migration Helper

Use Case: Validate and generate database migrations