gh-nemori-ai-skills-skill-customizer/skills/skill-customizer/references/customization_patterns.md

Customization Patterns Reference

This comprehensive guide provides detailed examples, patterns, and best practices for customizing skills effectively.

Table of Contents

1. Modification Patterns by Type
2. Before/After Examples
3. Common Challenges and Solutions
4. Advanced Techniques
5. Maintenance Best Practices

---

Modification Patterns by Type

Pattern 1: Output Format Customization

Use case: User prefers a different output format than the skill's default

Common scenarios:

• JSON → Markdown conversion
• Adding/removing metadata fields
• Changing table formats
• Customizing citations or references

Implementation approach:

1. Simple format preference (Markdown vs JSON):

   • Modify SKILL.md to specify new default format
   • Update examples to show new format
   • If script-based, add format parameter to scripts

2. Complex formatting requirements (company style guide):

   • Create scripts/custom_formatter.py with formatting functions
   • Add references/format_guide.md with detailed specifications
   • Update SKILL.md to reference custom formatter
   • Provide examples of correctly formatted output

Example modification:

# Before (in SKILL.md):
## Output Format
Return results as JSON with the following structure:
{
  "title": "...",
  "content": "..."
}

# After (customized for Markdown preference):
## Output Format
Return results as Markdown with the following structure:

# [Title]

[Content]

Source: [Document name, page X]

Pattern 2: Workflow Simplification

Use case: User only uses a subset of the skill's features

Common scenarios:

• Removing unused sections from decision trees
• Focusing on a single primary workflow
• Eliminating optional features
• Streamlining for repetitive tasks

Implementation approach:

1. Identify core workflow:

   • Review user's actual usage patterns
   • Determine which features are never used
   • Identify the 80/20 of user's needs

2. Restructure SKILL.md:

   • Move primary workflow to the top
   • Simplify or remove unused sections
   • Update decision trees to reflect focused use case
   • Consolidate related operations

3. Update examples:

   • Replace generic examples with user-specific scenarios
   • Focus on most common tasks
   • Remove examples for unused features

Example modification:

# Before: Generic PDF skill with many capabilities
## Capabilities
1. Extract text
2. Extract tables
3. Extract images
4. Merge PDFs
5. Split PDFs
6. Rotate pages
7. Add watermarks
8. Fill forms

# After: Streamlined for table extraction use case
## Primary Workflow: Table Extraction

Extract tables from PDF documents and output as CSV.

### Quick Start
[Focused table extraction workflow]

### Advanced Options
- Multi-page table handling
- Custom column mapping
- Header detection

(Other capabilities removed or moved to appendix)

Pattern 3: Domain Context Addition

Use case: User works in a specialized domain requiring specific knowledge

Common scenarios:

• Adding industry terminology
• Including domain-specific schemas
• Incorporating regulatory requirements
• Adding company-specific processes

Implementation approach:

1. Create domain reference files:

   • references/domain_glossary.md - Terminology and definitions
   • references/domain_schemas.md - Data structures and standards
   • references/domain_workflows.md - Industry-specific processes

2. Update SKILL.md:

   • Add domain context to overview
   • Reference domain files in relevant sections
   • Include domain-specific examples
   • Adjust language for domain audience

3. Add domain assets:

   • Templates specific to the domain
   • Sample documents from the domain
   • Domain-specific boilerplate

Example modification:

# Before: Generic document processing
## Overview
Process documents to extract and analyze content.

# After: Healthcare-specific document processing
## Overview
Process healthcare documents (clinical notes, lab reports, discharge summaries)
according to HL7 and HIPAA standards. Extract structured medical information
while maintaining compliance with healthcare regulations.

## Domain Context
Load `references/medical_terminology.md` for standardized medical terms and codes.
Load `references/hipaa_compliance.md` for data handling requirements.

## Workflows
[Updated with healthcare-specific examples and terminology]

Pattern 4: Parameter Default Adjustment

Use case: User consistently uses different parameters than skill defaults

Common scenarios:

• Changing verbosity levels
• Adjusting processing thresholds
• Modifying timeout or retry settings
• Updating file format preferences

Implementation approach:

1. In SKILL.md:

   • Update default values in workflow descriptions
   • Modify examples to use new defaults
   • Document when non-default values might be appropriate

2. In scripts:

   • Change default parameter values in function signatures
   • Update configuration constants
   • Maintain backward compatibility if needed

Example modification:

# Before: scripts/extractor.py
def extract_text(pdf_path, verbosity='verbose'):
    """Extract text with verbose output by default"""
    if verbosity == 'verbose':
        # Include metadata, page numbers, formatting
        pass
    else:
        # Concise output
        pass

# After: Customized for concise preference
def extract_text(pdf_path, verbosity='concise'):
    """Extract text with concise output by default (customized)"""
    if verbosity == 'concise':
        # Clean text only
        pass
    else:
        # Include additional details
        pass

Pattern 5: Tool Integration

Use case: User wants to integrate with specific tools or services

Common scenarios:

• Adding API integrations
• Connecting to company databases
• Integrating with project management tools
• Automating with company workflows

Implementation approach:

1. Create integration scripts:

   • scripts/api_connector.py - Handle API authentication and calls
   • scripts/data_transformer.py - Convert between formats

2. Add integration documentation:

   • references/api_setup.md - Configuration instructions
   • references/authentication.md - Credential management

3. Update SKILL.md:

   • Add integration setup steps
   • Document new workflows enabled by integration
   • Provide troubleshooting guidance

Example modification:

# Added to SKILL.md:

## Notion Integration

This customized version integrates with Notion to automatically save processed
documents to your Notion workspace.

### Setup
1. Generate Notion API token (see references/notion_setup.md)
2. Set NOTION_TOKEN environment variable
3. Configure target database ID

### Workflow
After processing a document:
1. Extract content using standard workflow
2. Format for Notion (using scripts/notion_formatter.py)
3. Upload to specified Notion database
4. Return Notion page URL

### Scripts
- scripts/notion_connector.py - Handle Notion API calls
- scripts/notion_formatter.py - Convert to Notion blocks

---

Before/After Examples

Example 1: PDF Skill → My PDF Tables

Original use case: General PDF processing Customized use case: Quick table extraction for financial reports

Before: Generic PDF skill excerpt

## Capabilities

### Extract Text
Use pypdf or pdfplumber to extract text content...

### Extract Tables
Use pdfplumber to extract tables...
[Detailed multi-option workflow]

### Merge PDFs
Combine multiple PDF files...

### Split PDFs
Separate PDF into individual pages...

After: Streamlined for table extraction

## Primary Workflow: Financial Report Table Extraction

Extract tables from financial PDF reports and output as CSV files with
proper numeric formatting.

### Quick Workflow
1. Load PDF using pdfplumber
2. Detect tables on each page
3. Extract with financial number formatting preserved
4. Output as CSV with headers
5. Include source page reference

### Default Settings (Customized)
- Output format: CSV (not JSON)
- Number format: Preserve commas and decimal points
- Headers: Auto-detect from first row
- Multiple tables: Separate files with page suffix

### Example
Input: quarterly_report.pdf
Output: quarterly_report_p3_table1.csv, quarterly_report_p3_table2.csv

[Detailed table extraction code with financial formatting]

---
Note: Other PDF capabilities (merge, split, etc.) removed for focus.
Refer to base 'pdf' skill if needed.

Example 2: Internal Comms → Company X Communications

Original use case: General internal communications Customized use case: Company X-specific communication standards

Before: Generic internal comms

## Writing Status Updates

Write clear status updates for internal teams.

### Structure
- Summary
- Progress
- Blockers
- Next steps

### Tone
Professional and clear.

After: Company X customized

## Writing Status Updates (Company X Standard)

Follow Company X communication guidelines (references/company_style_guide.md).

### Structure (Company X Template)
1. **TL;DR** - One-sentence summary
2. **Highlights** - 3-5 bullet points (emoji required per style guide)
3. **Metrics** - Include OKR alignment
4. **Blockers** - Use RAG status (Red/Amber/Green)
5. **Next Steps** - Include owner and due date
6. **Links** - Notion doc, Jira tickets, Slack thread

### Tone
Match Company X voice:
- Casual but professional
- Use "we" not "I"
- Default to transparent/public sharing
- Include memes/GIFs when appropriate

### Template
Use assets/company_x_status_template.md as starting point.

### Example Output
[Shows Company X-specific format with emojis, RAG status, etc.]

Example 3: Canvas Design → Medical Infographic Designer

Original use case: General visual design Customized use case: Medical education infographics

Before: Generic design instructions

## Design Principles
- Use color theory for visual hierarchy
- Balance composition
- Choose appropriate typography
- Create clear focal points

After: Medical infographic specific

## Medical Infographic Design Principles

Follow medical education best practices and accessibility standards.

### Color Requirements
- Use colorblind-safe palette (references/medical_colors.md)
- Avoid red/green for critical distinctions
- High contrast ratios (WCAG AAA)
- Use color + pattern for differentiation

### Typography
- Sans-serif for body (Arial, Helvetica)
- Minimum 14pt for body text (readability for all ages)
- Medical terms in bold on first use
- Include pronunciation guides for complex terms

### Medical Content Standards
- Cite sources (AMA format)
- Include disclaimer for educational use
- Use anatomically correct illustrations from assets/medical_images/
- Follow HIPAA guidelines for any patient data

### Layout
- Clear information hierarchy (diagnosis → symptoms → treatment)
- Use flowcharts for decision trees
- Include legend for all symbols
- Mobile-friendly formatting (many clinicians use tablets)

### Assets
- assets/anatomical_illustrations/ - Approved medical illustrations
- assets/medical_icons/ - Standard medical symbol set
- assets/citation_template.txt - AMA citation format

---

Common Challenges and Solutions

Challenge 1: Balancing Customization vs. Reusability

Problem: Over-customizing for a single task makes the skill too narrow

Solutions:

1. Parameterize instead of hardcode:

   • Use configuration files for user-specific values
   • Make customizations optional/togglable
   • Provide defaults but allow overrides

2. Document the scope:

   • Clearly state what the customized skill is for
   • List related use cases it still supports
   • Note when to use base skill vs. customized version

3. Version thoughtfully:

   • Keep base fork for general use
   • Create specialized forks for very specific needs
   • Document fork relationships

Example:

# In SKILL.md metadata:
metadata:
  customized-from: pdf
  customization-scope: Financial report table extraction
  also-works-for: Quarterly reports, balance sheets, income statements
  not-suitable-for: Image extraction, form filling, general PDFs

Challenge 2: Keeping Customizations Maintainable

Problem: Hard to remember what was changed and why after time passes

Solutions:

1. Comprehensive CUSTOMIZATION_LOG.md:

   • Document every change with rationale
   • Include "why" not just "what"
   • Note testing procedures

2. Inline comments in modified scripts:

   # CUSTOMIZED: Changed default from 'verbose' to 'concise'
   # Reason: User preference for minimal output (see CUSTOMIZATION_LOG v1.1)
   def process(verbosity='concise'):
       pass
   

3. Version number in SKILL.md:

   metadata:
     customization-version: 2.3
     last-updated: 2025-10-21
   

Challenge 3: Merging Updates from Base Skill

Problem: Base skill gets updates/improvements that you want in customized version

Solutions:

1. Track base skill version:

   metadata:
     customized-from: pdf
     base-skill-version: 1.0
     last-sync-date: 2025-10-21
   

2. Manual merge process:

   • Review base skill changelog
   • Identify relevant updates
   • Apply updates manually to customized version
   • Test thoroughly
   • Update metadata

3. Minimize deep modifications:

   • Prefer additions over modifications when possible
   • Use wrapper scripts instead of editing base scripts
   • Keep modifications isolated and documented

Challenge 4: Multiple Users with Different Preferences

Problem: Team wants shared skill but members have different preferences

Solutions:

1. Configuration-driven approach:

   • Create config.yaml for user preferences
   • Each user maintains their own config
   • Skill reads config at runtime

   # scripts/config.py
   import yaml
   
   def load_user_config():
       config_path = Path.home() / '.skill-config' / 'pdf-config.yaml'
       if config_path.exists():
           return yaml.safe_load(config_path.read_text())
       return default_config()
   

2. Profile-based customization:

   • Create named profiles (analyst, researcher, designer)
   • User selects profile at runtime
   • Skill applies profile-specific settings

3. Fork per user or team:

   • Maintain individual forks for strongly divergent needs
   • Share common base scripts as library
   • Document fork relationships

Challenge 5: Testing Customized Skills

Problem: Ensuring customizations work as intended without breaking functionality

Solutions:

1. Maintain test cases:

   • Document specific test scenarios in CUSTOMIZATION_LOG.md
   • Keep sample input files in tests/ directory
   • Define expected outputs for each customization

2. Before/after comparison:

   • Run same task on base skill and customized skill
   • Compare outputs
   • Verify customizations took effect
   • Check for unintended side effects

3. Regression testing:

   • Test previous use cases when adding new customizations
   • Ensure new changes don't break earlier improvements
   • Maintain a test checklist

Example test checklist:

# Test Checklist for my-pdf-tables v2.1

- [ ] Basic table extraction works
- [ ] Financial numbers preserve formatting
- [ ] Multi-page tables handled correctly
- [ ] CSV output has correct headers
- [ ] Page numbers included in filename
- [ ] Previous customizations still work:
  - [ ] v1.1: Concise output format
  - [ ] v1.5: Auto-header detection
  - [ ] v2.0: Multiple table separation

---

Advanced Techniques

Technique 1: Layered Customization

Create a hierarchy of customizations for progressive specialization:

pdf (base skill)
  └── my-pdf-workflow (general personal customizations)
      ├── financial-pdf (financial reports)
      └── research-pdf (academic papers)

Implementation:

1. First fork: Personal preferences (output format, defaults)
2. Second fork: Domain-specific (financial vs. research)
3. Document fork hierarchy in metadata

Benefits:

• Share common customizations
• Specialize without duplication
• Easy to maintain related forks

Technique 2: Plugin/Extension Pattern

Design customizations as plugins that extend base skill without modifying it:

Structure:

my-pdf/
  ├── SKILL.md (references base + extensions)
  ├── scripts/
  │   ├── extensions/
  │   │   ├── financial_formatter.py
  │   │   └── auto_namer.py
  └── references/
      └── base_skill.md (copy of original for reference)

In SKILL.md:

## Base Capabilities
Refer to references/base_skill.md for standard PDF operations.

## Extensions
This customized version adds:
- Financial number formatting (scripts/extensions/financial_formatter.py)
- Smart file naming (scripts/extensions/auto_namer.py)

Use base capabilities as documented, then apply extensions as needed.

Benefits:

• Clear separation of base vs. custom
• Easier to maintain
• Simple to add/remove extensions

Technique 3: Template-Based Customization

For skills that generate content, use templates to customize output:

Structure:

my-comms/
  ├── SKILL.md
  ├── scripts/
  │   └── template_renderer.py
  └── assets/
      ├── templates/
      │   ├── status_update.md
      │   ├── project_brief.md
      │   └── incident_report.md

Usage:

# scripts/template_renderer.py
from jinja2 import Template

def render_status_update(data):
    template_path = Path('assets/templates/status_update.md')
    template = Template(template_path.read_text())
    return template.render(**data)

Benefits:

• Easy to customize without code changes
• Non-technical users can update templates
• Consistent formatting across outputs

Technique 4: Conditional Behavior Based on Context

Adapt skill behavior based on detected context:

# scripts/context_detector.py

def detect_context(document_path):
    """Detect document type/context to apply appropriate customizations"""
    content = read_document(document_path)

    if 'QUARTERLY REPORT' in content[:1000]:
        return 'financial_quarterly'
    elif 'BALANCE SHEET' in content[:1000]:
        return 'financial_balance'
    elif 'CLINICAL NOTES' in content[:500]:
        return 'medical_clinical'
    else:
        return 'general'

def process_with_context(document_path):
    context = detect_context(document_path)

    if context == 'financial_quarterly':
        return process_financial_quarterly(document_path)
    elif context == 'medical_clinical':
        return process_medical_clinical(document_path)
    else:
        return process_general(document_path)

Benefits:

• Single skill handles multiple specialized scenarios
• Automatic context adaptation
• User doesn't need to specify type

Technique 5: Feedback-Driven Auto-Refinement

Build in feedback collection and analysis:

# scripts/track_usage.py

def log_usage(task_type, user_satisfaction, notes):
    """Log usage to identify improvement opportunities"""
    usage_log = Path('USAGE_LOG.jsonl')

    entry = {
        'timestamp': datetime.now().isoformat(),
        'task_type': task_type,
        'satisfaction': user_satisfaction,  # 1-5
        'notes': notes
    }

    with open(usage_log, 'a') as f:
        f.write(json.dumps(entry) + '\n')

def analyze_usage_patterns():
    """Analyze usage log to identify customization opportunities"""
    # Find low-satisfaction tasks
    # Identify common pain points
    # Suggest targeted improvements
    pass

Benefits:

• Data-driven customization decisions
• Identify patterns over time
• Prioritize highest-impact improvements

---

Maintenance Best Practices

Best Practice 1: Regular Review Cycles

Schedule: Review customized skills quarterly or after major projects

Review checklist:

• Are customizations still relevant?
• Any new pain points to address?
• Can any customizations be generalized?
• Are there unused customizations to remove?
• Does documentation need updates?

Best Practice 2: Version Control

Use git or similar for tracking changes:

cd my-customized-skill/
git init
git add .
git commit -m "Initial fork from base skill"

# After each customization iteration
git add .
git commit -m "v1.1: Changed default output format to Markdown

- Modified SKILL.md output section
- Updated examples
- Tested on sample documents

Addresses feedback from 2025-10-15"

Benefits:

• Track change history
• Easy to revert problematic changes
• Collaborate with others
• Maintain multiple versions

Best Practice 3: Documentation as Code

Keep documentation close to implementation:

# scripts/financial_formatter.py
"""
Financial number formatter for PDF table extraction

Customization History:
- v1.1 (2025-10-15): Added comma preservation
- v1.2 (2025-10-18): Added currency symbol detection
- v2.0 (2025-10-20): Support for European number formats

Related customization log entries: v1.1, v1.2, v2.0
"""

def format_financial_number(value, preserve_commas=True):
    """
    Format extracted number for financial reports

    Args:
        value: Extracted number string
        preserve_commas: Keep thousand separators (default: True per v1.1)

    Returns:
        Formatted number string

    Examples:
        >>> format_financial_number("1,234.56")
        "1,234.56"

        >>> format_financial_number("1.234,56")  # European format, v2.0
        "1.234,56"
    """
    pass

Best Practice 4: Maintain a CHANGELOG

Separate from CUSTOMIZATION_LOG.md, maintain a user-facing changelog:

# Changelog: my-pdf-tables

## [2.0.0] - 2025-10-20
### Added
- Support for European number formats (commas/periods swapped)
- Auto-detection of number format from document locale

### Changed
- Default output includes source page numbers
- Table headers now auto-detected (previously manual)

### Fixed
- Multi-page tables no longer split incorrectly

## [1.2.0] - 2025-10-18
### Added
- Currency symbol detection and preservation
- Support for parenthetical negative numbers (accounting format)

## [1.1.0] - 2025-10-15
### Changed
- Default output format: CSV (was JSON)
- Preserve comma thousand separators (was stripping)

### Removed
- Unused image extraction code from base skill

## [1.0.0] - 2025-10-10
### Added
- Initial fork from 'pdf' base skill
- Focus on table extraction workflow

Best Practice 5: Share and Learn

Within teams:

• Share successful customization patterns
• Document what worked and what didn't
• Create organization-wide customization library
• Hold periodic skill review sessions

With community:

• Contribute useful patterns back to base skills
• Share generalized customizations
• Learn from others' customization approaches

Documentation:

• Maintain README.md for customized skill
• Include setup instructions
• Document prerequisites
• Provide troubleshooting guide

---

Quick Reference: When to Use Each Pattern

Scenario	Recommended Pattern	Key Resources
Different output format	Output Format Customization	Modify SKILL.md, add formatter script
Only use subset of features	Workflow Simplification	Restructure SKILL.md, remove unused sections
Specialized domain/industry	Domain Context Addition	Add references/, update examples
Different default settings	Parameter Default Adjustment	Update SKILL.md, modify script defaults
Need to connect to other tools	Tool Integration	Add scripts/, integration docs
Team with varying preferences	Configuration-driven	Add config.yaml, profile system
Progressive specialization	Layered Customization	Multiple forks in hierarchy
Extend without modifying	Plugin/Extension Pattern	Extension scripts, modular design
Content generation	Template-Based	Templates in assets/, renderer script
Handle multiple scenarios	Conditional Behavior	Context detector, branching logic

---

Conclusion

Effective skill customization is an iterative process that balances specificity with reusability. Use these patterns as starting points, adapt them to your needs, and always document your customizations thoroughly for future reference.

Remember:

• Start small with targeted improvements
• Test each customization thoroughly
• Document rationale, not just changes
• Review and refine regularly
• Share learnings with others