gh-francyjglisboa-agent-skill-creator/docs/NAMING_CONVENTIONS.md

Naming Conventions: The "-cskill" Suffix

🎯 Purpose and Overview

This document establishes the mandatory naming convention for all Claude Skills created by Agent-Skill-Creator, using the "-cskill" suffix to ensure clear identification and professional consistency.

🏷️ The "-cskill" Suffix

Meaning

• CSKILL = Claude SKILL
• Indicates the skill was automatically created by Agent-Skill-Creator
• Differentiates from manually created skills or other tools

Benefits

✅ Immediate Identification

• Anyone sees "-cskill" and immediately knows it's a Claude Skill
• Instant recognition of origin (Agent-Skill-Creator)

✅ Easy Organization

• Easy to filter and find skills created by the creator
• Logical grouping in file systems
• Efficient search with consistent pattern

✅ Professionalism

• Professional and standardized naming convention
• Clarity in communication about origin and type
• Organized and intentional appearance

✅ Avoids Confusion

• No ambiguity about what's a skill vs plugin
• Clear distinction between manual vs automated skills
• Prevention of name conflicts

📋 Naming Rules

1. Mandatory Format

{descriptive-description}-cskill/

2. Base Name Structure

Simple Skills (Single Objective)

{action}-{object}-csskill/

Examples:

• pdf-text-extractor-cskill/
• csv-data-cleaner-cskill/
• image-converter-cskill/
• email-automation-cskill/
• report-generator-cskill/

Complex Skill Suites (Multiple Components)

{domain}-analysis-suite-cskill/
{domain}-automation-cskill/
{domain}-workflow-cskill/

Examples:

• financial-analysis-suite-cskill/
• e-commerce-automation-cskill/
• research-workflow-cskill/
• business-intelligence-cskill/

Component Skills (Within Suites)

{functionality}-{domain}-cskill/

Examples:

• data-acquisition-cskill/
• technical-analysis-cskill/
• reporting-generator-cskill/
• user-interface-cskill/

3. Formatting Rules

✅ REQUIRED:

• Always lowercase
• Use hyphens (-) to separate words
• End with "-cskill"
• Be descriptive and clear
• Use only alphanumeric characters and hyphens

❌ PROHIBITED:

• Uppercase letters
• Underscores (_)
• Whitespace
• Special characters (!@#$%&*)
• Numbers at the beginning
• Non-standard abbreviations

4. Recommended Length

• Minimum: 10 characters (ex: pdf-tool-cskill)
• Ideal: 20-40 characters (ex: financial-analysis-suite-cskill)
• Maximum: 60 characters (justified exceptions)

🔧 Name Generation Process

Agent-Skill-Creator Automatic Logic

def generate_skill_name(user_requirements, complexity):
    """
    Generates skill name following -cskill convention
    """

    # 1. Extract key concepts from user input
    concepts = extract_key_concepts(user_requirements)

    # 2. Create base name based on complexity
    if complexity == "simple":
        base_name = create_simple_name(concepts)
    elif complexity == "complex_suite":
        base_name = create_suite_name(concepts)
    else:  # hybrid
        base_name = create_hybrid_name(concepts)

    # 3. Sanitize and format
    base_name = sanitize_name(base_name)

    # 4. Apply -cskill convention
    skill_name = f"{base_name}-cskill"

    return skill_name

def create_simple_name(concepts):
    """Creates name for simple skills"""
    if len(concepts) == 1:
        return f"{concepts[0]}-tool"
    elif len(concepts) == 2:
        return f"{concepts[1]}-{concepts[0]}"
    else:
        return "-".join(concepts[:2])

def create_suite_name(concepts):
    """Creates name for complex suites"""
    if len(concepts) <= 2:
        return f"{concepts[0]}-automation"
    else:
        return f"{concepts[0]}-{'-'.join(concepts[1:3])}-suite"

def sanitize_name(name):
    """Sanitizes name to valid format"""
    # Convert to lowercase
    name = name.lower()
    # Replace spaces and underscores with hyphens
    name = re.sub(r'[\s_]+', '-', name)
    # Remove special characters
    name = re.sub(r'[^a-z0-9-]', '', name)
    # Remove multiple hyphens
    name = re.sub(r'-+', '-', name)
    # Remove hyphens at start/end
    name = name.strip('-')
    return name

Transformation Examples

User Input	Type	Extracted Concepts	Generated Name
"Extract text from PDF"	Simple	["extract", "text", "pdf"]	pdf-text-extractor-cskill/
"Clean CSV data automatically"	Simple	["clean", "csv", "data"]	csv-data-cleaner-cskill/
"Complete financial analysis platform"	Suite	["financial", "analysis", "platform"]	financial-analysis-suite-cskill/
"Automate e-commerce workflows"	Suite	["automate", "ecommerce", "workflows"]	ecommerce-automation-cskill/
"Generate weekly status reports"	Simple	["generate", "weekly", "reports"]	weekly-report-generator-cskill/

📚 Practical Examples by Domain

Finance and Investments

financial-analysis-suite-cskill/
portfolio-optimizer-cskill/
market-data-fetcher-cskill/
risk-calculator-cskill/
trading-signal-generator-cskill/

Data Analysis

data-visualization-cskill/
statistical-analysis-cskill/
etl-pipeline-cskill/
data-cleaner-cskill/
dashboard-generator-cskill/

Document Automation

pdf-processor-cskill/
word-automation-cskill/
excel-report-generator-cskill/
presentation-creator-cskill/
document-converter-cskill/

E-commerce and Sales

inventory-tracker-cskill/
sales-analytics-cskill/
customer-data-processor-cskill/
order-automation-cskill/
price-monitor-cskill/

Research and Academia

literature-review-cskill/
citation-manager-cskill/
research-data-collector-cskill/
academic-paper-generator-cskill/
survey-analyzer-cskill/

Productivity and Office

email-automation-cskill/
calendar-manager-cskill/
task-tracker-cskill/
note-organizer-cskill/
meeting-scheduler-cskill/

🔍 Validation and Quality

Automatic Verification

def validate_skill_name(skill_name):
    """
    Validates if name follows -cskill convention
    """

    # 1. Check -cskill suffix
    if not skill_name.endswith("-cskill"):
        return False, "Missing -cskill suffix"

    # 2. Check lowercase format
    if skill_name != skill_name.lower():
        return False, "Must be lowercase"

    # 3. Check valid characters
    if not re.match(r'^[a-z0-9-]+-cskill$', skill_name):
        return False, "Contains invalid characters"

    # 4. Check length
    if len(skill_name) < 10 or len(skill_name) > 60:
        return False, "Invalid length"

    # 5. Check consecutive hyphens
    if '--' in skill_name:
        return False, "Contains consecutive hyphens"

    return True, "Valid naming convention"

Quality Checklist

For each generated name, verify:

• Ends with "-cskill" ✓
• Is in lowercase ✓
• Uses only hyphens as separators ✓
• Is descriptive and clear ✓
• Has no special characters ✓
• Appropriate length (10-60 characters) ✓
• Easy to pronounce and remember ✓
• Reflects main functionality ✓
• Is unique in ecosystem ✓

🚀 Best Practices

1. Be Descriptive

✅ good: pdf-text-extractor-cskill
❌ bad: tool-cskill

✅ good: financial-analysis-suite-cskill
❌ bad: finance-cskill

2. Keep It Simple

✅ good: csv-data-cleaner-cskill
❌ bad: automated-csv-data-validation-and-cleaning-tool-cskill

✅ good: email-automation-cskill
❌ bad: professional-email-marketing-automation-workflow-cskill

3. Be Consistent

✅ good: data-acquisition-cskill, data-processing-cskill, data-visualization-cskill
❌ bad: get-data-cskill, process-cskill, visualize-cskill

4. Think About the User

✅ good: weekly-report-generator-cskill (clear what it does)
❌ bad: wrk-gen-cskill (abbreviated, confusing)

🔄 Migration and Legacy

Existing Skills Without "-cskill"

If you have existing skills without the suffix:

1. Add the suffix immediately

   mv old-skill-name old-skill-name-cskill
   

2. Update internal references

   • Update SKILL.md
   • Modify marketplace.json
   • Update documentation

3. Test functionality

   • Verify skill still works
   • Confirm correct installation

Migration Documentation

For each migrated skill, document:

## Migration History
- **Original Name**: `old-name`
- **New Name**: `old-name-cskill`
- **Migration Date**: YYYY-MM-DD
- **Reason**: Apply -cskill naming convention
- **Impact**: None, purely cosmetic change

📖 Quick Reference Guide

To Create New Name:

1. Identify main objective (ex: "extract PDF text")
2. Extract key concepts (ex: extract, pdf, text)
3. Build base name (ex: pdf-text-extractor)
4. Add suffix (ex: pdf-text-extractor-cskill)

To Validate Existing Name:

1. Check "-cskill" suffix
2. Confirm lowercase format
3. Check valid characters
4. Evaluate descriptiveness

To Troubleshoot:

• Name too short: Add descriptor
• Name too long: Remove secondary words
• Confusing name: Use clearer synonyms
• Name conflict: Add differentiator

✅ Convention Summary

Formula: {descriptive-description}-cskill/

Essential Rules:

• ✅ Always end with "-cskill"
• ✅ Always lowercase
• ✅ Use hyphens as separators
• ✅ Be descriptive and clear

Results:

• 🎯 Immediate identification as Claude Skill
• 🏗️ Clear origin (Agent-Skill-Creator)
• 📁 Easy organization
• 🔍 Efficient search
• 💬 Clear communication

This convention ensures professional consistency and eliminates any confusion about the origin and type of created skills!