zhongwei/gh-bbrowning-bbrowning-claude-marketplace-bbrowning-claude

Fork 0

Files

Zhongwei Li cc49e355bc Initial commit

2025-11-29 18:00:42 +08:00

17 KiB

Raw Blame History

Skill Examples

Real-world examples of well-crafted skills demonstrating best practices.

Example 1: Simple Focused Skill

A single-purpose skill with everything in SKILL.md.

Directory Structure

changelog-generator/
└── SKILL.md

SKILL.md

---
name: Generating Changelog Entries
description: Creates standardized changelog entries from git commits following Keep a Changelog format with semantic versioning categories
---

# Generating Changelog Entries

Creates changelog entries in Keep a Changelog format from git commit history.

## Workflow

1. Review git commits since last release
2. Categorize commits:
   - **Added**: New features
   - **Changed**: Changes to existing functionality
   - **Deprecated**: Soon-to-be removed features
   - **Removed**: Removed features
   - **Fixed**: Bug fixes
   - **Security**: Security improvements
3. Format as markdown under appropriate headings
4. Include commit hashes as references

## Output Format

\`\`\`markdown
## [Version] - YYYY-MM-DD

### Added
- New feature description [abc123]

### Fixed
- Bug fix description [def456]
\`\`\`

## Examples

### Input Commits

abc123 feat: Add user authentication def456 fix: Resolve login timeout issue ghi789 docs: Update README


### Output
```markdown
## [1.2.0] - 2024-01-15

### Added
- User authentication system [abc123]

### Fixed
- Login timeout issue [def456]

Validation

Ensure:

All commits are categorized
Date is in YYYY-MM-DD format
Version follows semantic versioning
Each entry includes commit hash


**Why this works**:
- Focused on one task
- Clear categorization
- Specific format
- Concrete example
- Validation checklist

## Example 2: Skill with Reference Documentation

A skill using progressive disclosure for complex information.

### Directory Structure

api-doc-generator/ ├── SKILL.md └── reference/ ├── jsdoc-patterns.md └── openapi-spec.md


### SKILL.md
```markdown
---
name: Generating API Documentation
description: Creates comprehensive API documentation from JSDoc comments including endpoints, parameters, responses, and examples in OpenAPI 3.0 format
---

# Generating API Documentation

Generates API documentation in OpenAPI 3.0 format from JSDoc-annotated code.

## Overview

Extracts API information from JSDoc comments and produces OpenAPI specification with:
- Endpoint descriptions
- Request/response schemas
- Authentication requirements
- Example payloads

## Workflow

1. Scan codebase for JSDoc-annotated API endpoints
2. Extract route, method, parameters, responses
3. Generate OpenAPI schema definitions
4. Create example requests/responses
5. Validate against OpenAPI 3.0 specification

## JSDoc Pattern

Expected JSDoc format:
\`\`\`javascript
/**
 * @api {get} /users/:id Get User
 * @apiParam {String} id User ID
 * @apiSuccess {Object} user User object
 * @apiSuccess {String} user.name User name
 */
\`\`\`

For detailed JSDoc patterns, see `reference/jsdoc-patterns.md`.

## Output Format

Generate OpenAPI 3.0 YAML. For complete specification reference, see `reference/openapi-spec.md`.

Basic structure:
\`\`\`yaml
openapi: 3.0.0
info:
  title: API Name
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get User
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
\`\`\`

## Validation

1. Validate YAML syntax
2. Verify against OpenAPI 3.0 schema
3. Ensure all referenced schemas are defined
4. Check examples match schema definitions

reference/jsdoc-patterns.md

# JSDoc Patterns for API Documentation

Complete reference for supported JSDoc annotations.

## Basic Endpoint

\`\`\`javascript
/**
 * @api {method} /path Description
 * @apiName UniqueName
 * @apiGroup GroupName
 */
\`\`\`

## Parameters

[... detailed parameter documentation ...]

## Responses

[... detailed response documentation ...]

## Examples

[... 20+ examples of different patterns ...]

Why this works:

Core workflow in SKILL.md
Extended details in reference files
Clear references to additional docs
Progressive disclosure

Example 3: Skill with Scripts

A skill using deterministic scripts for validation.

Directory Structure

invoice-processor/
├── SKILL.md
├── scripts/
│   ├── extract-data.py
│   └── validate-output.py
└── templates/
    └── invoice-output.json

SKILL.md

---
name: Processing Invoice PDFs
description: Extracts structured data from invoice PDFs including vendor, date, line items, and totals with validation against expected schema
---

# Processing Invoice PDFs

Extracts and validates invoice data from PDF files.

## Workflow

1. Use `scripts/extract-data.py` to extract text from PDF
2. Parse extracted text for key fields:
   - Vendor name
   - Invoice number
   - Date (YYYY-MM-DD)
   - Line items (description, quantity, unit price, total)
   - Subtotal, tax, total
3. Structure as JSON matching `templates/invoice-output.json`
4. Validate using `scripts/validate-output.py`

## Extraction Script

\`\`\`bash
python scripts/extract-data.py input.pdf output.txt
\`\`\`

Outputs raw text from PDF for parsing.

## Output Format

Follow the schema in `templates/invoice-output.json`:

\`\`\`json
{
  "vendor": "Company Name",
  "invoice_number": "INV-001",
  "date": "2024-01-15",
  "line_items": [
    {
      "description": "Item description",
      "quantity": 2,
      "unit_price": 50.00,
      "total": 100.00
    }
  ],
  "subtotal": 100.00,
  "tax": 8.00,
  "total": 108.00
}
\`\`\`

## Validation

Run validation script:
\`\`\`bash
python scripts/validate-output.py output.json
\`\`\`

Validates:
- All required fields present
- Date format is YYYY-MM-DD
- Calculations are correct (line totals, subtotal, tax, total)
- Numbers are properly formatted

Exit code 0 = valid, 1 = validation errors (prints details).

## Error Handling

If extraction fails:
1. Check PDF is not password-protected
2. Verify PDF contains text (not scanned image)
3. Review raw extracted text for parsing issues

scripts/validate-output.py

#!/usr/bin/env python3
"""
Validates invoice JSON output.

Usage:
    python validate-output.py invoice.json

Exit codes:
    0: Valid
    1: Validation errors
"""
import sys
import json
from datetime import datetime

def validate_invoice(data):
    errors = []

    # Required fields
    required = ['vendor', 'invoice_number', 'date', 'line_items', 'total']
    for field in required:
        if field not in data:
            errors.append(f"Missing required field: {field}")

    # Date format
    try:
        datetime.strptime(data['date'], '%Y-%m-%d')
    except ValueError:
        errors.append(f"Invalid date format: {data['date']}")

    # Calculate totals
    calculated_total = sum(item['total'] for item in data['line_items'])
    if abs(calculated_total - data['subtotal']) > 0.01:
        errors.append(f"Subtotal mismatch: {data['subtotal']} != {calculated_total}")

    return errors

def main():
    if len(sys.argv) != 2:
        print("Usage: validate-output.py invoice.json", file=sys.stderr)
        sys.exit(1)

    with open(sys.argv[1]) as f:
        data = json.load(f)

    errors = validate_invoice(data)

    if errors:
        print("Validation errors:", file=sys.stderr)
        for error in errors:
            print(f"  - {error}", file=sys.stderr)
        sys.exit(1)

    print("Validation successful")
    sys.exit(0)

if __name__ == "__main__":
    main()

Why this works:

Scripts handle deterministic operations
Clear script usage documentation
Template provides expected format
Validation ensures correctness
Error handling guidance

Example 4: Tool-Restricted Skill

A skill with restricted tool access for safety.

Directory Structure

security-audit/
└── SKILL.md

SKILL.md

---
name: Auditing Security Configurations
description: Reviews configuration files for security vulnerabilities including exposed secrets, weak permissions, and insecure defaults without modifying any files
allowed-tools: [Read, Grep, Glob]
---

# Auditing Security Configurations

Performs read-only security audit of configuration files.

## Tool Restrictions

This skill is read-only. Only these tools are available:
- Read: Read files
- Grep: Search for patterns
- Glob: Find files

This ensures no accidental modifications during security audit.

## Audit Checklist

### 1. Secrets Exposure
Search for potential secrets:
\`\`\`bash
grep -r "api_key\|password\|secret\|token" .
\`\`\`

Check for:
- Hardcoded passwords
- API keys in code
- Exposed tokens
- Committed .env files

### 2. File Permissions
Review files that should have restricted permissions:
- Private keys (.pem, .key)
- Configuration files with secrets
- Database credentials

### 3. Insecure Defaults
Check configurations for:
- Debug mode enabled in production
- CORS set to allow all origins
- Disabled authentication
- Exposed admin interfaces

## Output Format

Generate markdown report:

\`\`\`markdown
# Security Audit Report

## Critical Issues
- [Issue description] - [File:Line]

## Warnings
- [Issue description] - [File:Line]

## Recommendations
1. [Recommendation]
2. [Recommendation]
\`\`\`

## Examples

### Finding: Exposed Secret
\`\`\`
## Critical Issues
- Hardcoded API key in source code - config/api.js:12
  \`\`\`
  const API_KEY = "sk_live_abc123xyz"
  \`\`\`
  Recommendation: Move to environment variable

Why this works:

Tool restrictions prevent modifications
Clear audit methodology
Structured output format
Safety-critical workflow

Example 5: Complex Multi-File Skill

A comprehensive skill with full progressive disclosure.

Directory Structure

react-component-generator/
├── SKILL.md
├── reference/
│   ├── typescript-patterns.md
│   ├── testing-guide.md
│   └── styling-conventions.md
├── scripts/
│   └── validate-component.sh
└── templates/
    ├── component.tsx
    ├── component.test.tsx
    └── component.styles.ts

SKILL.md

---
name: Creating React Components
description: Generates TypeScript React components following project conventions including component structure, PropTypes, styled-components, and comprehensive Jest tests with React Testing Library
---

# Creating React Components

Generates production-ready React components with TypeScript, tests, and styles.

## Overview

Creates a complete React component with:
- TypeScript component file
- Styled-components styling
- Jest + React Testing Library tests
- Prop validation
- JSDoc documentation

## Workflow

1. Create component file using `templates/component.tsx` as base
2. Define TypeScript interface for props
3. Implement component logic
4. Create styled-components in `templates/component.styles.ts` pattern
5. Write tests following `templates/component.test.tsx`
6. Validate with `scripts/validate-component.sh`

## Component Structure

See `templates/component.tsx` for complete structure. Key elements:

\`\`\`typescript
interface ComponentProps {
  // Props with JSDoc
}

export const Component: React.FC<ComponentProps> = ({ props }) => {
  // Implementation
}
\`\`\`

## TypeScript Patterns

For TypeScript best practices, see `reference/typescript-patterns.md`.

Key patterns:
- Use interfaces for props
- Avoid 'any' type
- Leverage union types for variants
- Use generics for reusable components

## Styling

Follow styled-components patterns in `reference/styling-conventions.md`.

Basic pattern from `templates/component.styles.ts`:
\`\`\`typescript
import styled from 'styled-components'

export const Container = styled.div\`
  // Styles
\`
\`\`\`

## Testing

Follow testing guide in `reference/testing-guide.md`.

Use template from `templates/component.test.tsx`:
- Test rendering
- Test interactions
- Test edge cases
- Test accessibility

## Validation

Run validation:
\`\`\`bash
./scripts/validate-component.sh src/components/MyComponent
\`\`\`

Checks:
- TypeScript compiles
- Tests pass
- Linting passes
- No console errors

## File Naming

\`\`\`
src/components/MyComponent/
├── MyComponent.tsx
├── MyComponent.test.tsx
├── MyComponent.styles.ts
└── index.ts
\`\`\`

reference/typescript-patterns.md

# TypeScript Patterns for React Components

[Detailed TypeScript patterns, 200+ lines]

reference/testing-guide.md

# Testing Guide for React Components

[Comprehensive testing patterns, 300+ lines]

reference/styling-conventions.md

# Styling Conventions with styled-components

[Detailed styling patterns, 150+ lines]

templates/component.tsx

import React from 'react'
import { Container } from './ComponentName.styles'

interface ComponentNameProps {
  /**
   * Description of prop
   */
  propName: string
}

/**
 * ComponentName description
 *
 * @example
 * <ComponentName propName="value" />
 */
export const ComponentName: React.FC<ComponentNameProps> = ({
  propName
}) => {
  return (
    <Container>
      {propName}
    </Container>
  )
}

Why this works:

Concise SKILL.md (under 500 lines)
Progressive disclosure to reference docs
Templates provide starting points
Validation script ensures quality
Clear file organization

Example 6: Workflow-Driven Skill

A skill focused on a multi-step workflow with validation.

Directory Structure

database-migration/
└── SKILL.md

SKILL.md

---
name: Managing Database Migrations
description: Creates and applies database migrations with automated backup, validation, and rollback capabilities for PostgreSQL using Prisma
allowed-tools: [Read, Write, Bash, Grep, Glob]
---

# Managing Database Migrations

Safe database migration workflow with backup and rollback.

## Prerequisites

- Prisma CLI installed
- Database connection configured
- Write access to database

## Migration Workflow

### Creating a Migration

1. **Backup current schema**
   \`\`\`bash
   pg_dump -s database_name > backups/schema_$(date +%Y%m%d_%H%M%S).sql
   \`\`\`

2. **Create migration**
   \`\`\`bash
   npx prisma migrate dev --name migration_name
   \`\`\`

3. **Review generated SQL**
   - Check migration file in `prisma/migrations/`
   - Verify no unexpected changes
   - Ensure data integrity preserved

4. **Validate migration**
   - Test on local database first
   - Verify data not corrupted
   - Check application still works

### Applying to Production

1. **Create production backup**
   \`\`\`bash
   pg_dump database_name > backups/prod_backup_$(date +%Y%m%d_%H%M%S).sql
   \`\`\`

2. **Run migration**
   \`\`\`bash
   npx prisma migrate deploy
   \`\`\`

3. **Verify migration applied**
   \`\`\`bash
   npx prisma migrate status
   \`\`\`

4. **Validate data integrity**
   - Run integrity checks
   - Verify critical queries still work
   - Check row counts match expectations

### Rollback Procedure

If migration fails:

1. **Stop application** (prevent writes)

2. **Restore from backup**
   \`\`\`bash
   psql database_name < backups/prod_backup_TIMESTAMP.sql
   \`\`\`

3. **Verify restoration**
   - Check row counts
   - Run test queries
   - Verify application works

4. **Investigate failure**
   - Review migration SQL
   - Check error logs
   - Fix issue before retrying

## Safety Checklist

Before applying migration:
- [ ] Local backup created
- [ ] Migration tested on development database
- [ ] Migration SQL reviewed
- [ ] Production backup created
- [ ] Rollback procedure documented
- [ ] Maintenance window scheduled (if needed)

## Validation Queries

After migration, verify:

\`\`\`sql
-- Check table exists
SELECT EXISTS (
  SELECT FROM information_schema.tables
  WHERE table_name = 'table_name'
);

-- Verify row counts
SELECT COUNT(*) FROM critical_table;

-- Test critical queries
SELECT * FROM users WHERE id = 1;
\`\`\`

## Common Issues

### Issue: Migration fails mid-apply
**Solution**: Restore from backup, fix migration, retry

### Issue: Data type mismatch
**Solution**: Add explicit type conversion in migration

### Issue: Foreign key constraint violation
**Solution**: Ensure related data exists or use ON DELETE CASCADE

## Examples

### Example 1: Adding a Column
\`\`\`sql
ALTER TABLE users ADD COLUMN email_verified BOOLEAN DEFAULT false;
\`\`\`

### Example 2: Creating a Table
\`\`\`sql
CREATE TABLE audit_logs (
  id SERIAL PRIMARY KEY,
  user_id INTEGER REFERENCES users(id),
  action VARCHAR(255),
  created_at TIMESTAMP DEFAULT NOW()
);
\`\`\`

Why this works:

Clear step-by-step workflow
Safety measures at each step
Validation checkpoints
Rollback procedure
Tool restrictions for safety
Common issues documented

Key Takeaways from Examples

Simple skills: Everything in SKILL.md, focused on one task
Reference-based skills: Core in SKILL.md, details in reference/
Scripted skills: Use scripts for deterministic operations
Tool-restricted skills: Limit tools for safety-critical tasks
Complex skills: Full progressive disclosure with templates
Workflow skills: Step-by-step with validation and rollback

Each example demonstrates:

Clear, specific descriptions
Concrete examples
Validation steps
Appropriate level of detail
Progressive disclosure when needed
Focused purpose

Use these patterns as starting points for your own skills.

17 KiB Raw Blame History

Skill Examples

Example 1: Simple Focused Skill

Directory Structure

SKILL.md

Validation

reference/jsdoc-patterns.md

Example 3: Skill with Scripts

Directory Structure

SKILL.md

scripts/validate-output.py

Example 4: Tool-Restricted Skill

Directory Structure

SKILL.md

Example 5: Complex Multi-File Skill

Directory Structure

SKILL.md

reference/typescript-patterns.md

reference/testing-guide.md

reference/styling-conventions.md

templates/component.tsx

Example 6: Workflow-Driven Skill

Directory Structure

SKILL.md

Key Takeaways from Examples

17 KiB

Raw Blame History