skill-creator-expert

name	skill-creator-expert
version	1.0.0
description	Expert system for designing, creating, and validating PCL skills with comprehensive domain knowledge extraction
category	tools
tags	["skill-creation","meta-programming","domain-modeling","knowledge-engineering","pcl-development"]
allowed-tools	["Read","Write","Edit","Execute"]

Skill Creator Expert

Master skill architect for designing, implementing, and validating high-quality PCL skills. Specializes in domain knowledge extraction, skill composition patterns, and PCL best practices.

Core Competencies

Skill Design Principles

• Domain analysis and knowledge extraction
• Skill scope definition and boundaries
• Dependency mapping and composition
• Tool allowlist configuration
• Version management and evolution

Skill Architecture Patterns

• Single-responsibility skills
• Composite skills (orchestration)
• Hierarchical skill structures
• Cross-domain skill integration
• Reusable skill components

Quality & Validation

• Skill testing frameworks
• Documentation completeness
• Example scenario coverage
• Performance benchmarking
• Security review

Skill Creation Framework

1. Domain Analysis Template

interface DomainAnalysis {
  // Core domain identification
  domain: {
    name: string;
    category:
      | 'language'
      | 'framework'
      | 'cloud'
      | 'data'
      | 'devops'
      | 'ai'
      | 'security'
      | 'professional'
      | 'scientific'
      | 'tools'
      | 'domains';
    subcategories: string[];
    relatedDomains: string[];
  };

  // Knowledge extraction
  coreKnowledge: {
    fundamentals: string[];
    advancedConcepts: string[];
    bestPractices: string[];
    antiPatterns: string[];
    commonPitfalls: string[];
  };

  // Practical expertise
  practicalSkills: {
    codePatterns: CodePattern[];
    architecturePatterns: ArchitecturePattern[];
    toolingExpertise: string[];
    debuggingStrategies: string[];
    optimizationTechniques: string[];
  };

  // Real-world scenarios
  useCases: {
    beginner: [];
    : [];
    : [];
    : [];
  };

  
  : {
    : [];
    : [];
    : [];
  };
}

  {
  : ;
  : ;
  : ;
  : ;
  : ;
  : [];
}

  {
  : ;
  : ;
  : ;
  : ;
  : {
    : [];
    : [];
  };
}

  {
  : ;
  : ;
  : ;
  : ;
  : ;
  : ;
}

2. Skill Structure Generator

class SkillStructureGenerator {
  /**
   * Generate complete skill structure from domain analysis
   */
  generateSkill(analysis: DomainAnalysis): SkillDefinition {
    return {
      metadata: this.generateMetadata(analysis),
      frontMatter: this.generateFrontMatter(analysis),
      coreConcepts: this.extractCoreConcepts(analysis),
      codeExamples: this.generateCodeExamples(analysis),
      bestPractices: this.compileBestPractices(analysis),
      advancedPatterns: this.extractAdvancedPatterns(analysis),
      integrationGuide: this.generateIntegrationGuide(analysis),
      troubleshooting: this.generateTroubleshooting(analysis),
      references: this.gatherReferences(analysis),
    };
  }

  /**
   * Generate YAML front matter
   */
  private generateFrontMatter(analysis: DomainAnalysis): string {
    const tools = this.determineRequiredTools(analysis);
     tags = .(analysis);

     ;
  }

  
   (: ):  {
     {
      : ,
      : [
        {
          : ,
          : .(analysis..),
        },
        {
          : ,
          : .(
            analysis..
          ),
        },
        {
          : ,
          : .(
            analysis..
          ),
        },
      ],
    };
  }

  
   (: ):  {
     : [] = [];

    
     ( level  [
      ,
      ,
      ,
      ,
    ]  ) {
       scenarios = analysis.[level];
      scenarios.( {
        examples.({
          : scenario.,
          level,
          : scenario.,
          : scenario.,
          : scenario.,
        });
      });
    }

     .(examples);
  }

  
   (: ):  {
     practices = analysis...( ({
      practice,
      : .(practice, analysis),
      : .(practice, analysis),
      : .(practice, analysis),
    }));

     {
      : ,
      : .(practices),
    };
  }

  
   (: ):  {
     {
      : ,
      : analysis...(
         ({
          : pattern.,
          : .(pattern),
        })
      ),
    };
  }

  
   (: ):  {
     integrations = .(analysis);

     {
      : ,
      : [
        {
          : ,
          : .(analysis..),
        },
        {
          : ,
          : .(
            analysis..
          ),
        },
        {
          : ,
          : .(
            analysis..
          ),
        },
        {
          : ,
          : .(integrations),
        },
      ],
    };
  }

  
   (: ):  {
     issues = .(analysis);

     {
      : ,
      : issues.( .(issue)),
    };
  }

  
   (: ):  {
     {
      : ,
      : [
        {
          : ,
          : .(analysis..),
        },
        {
          : ,
          : .(analysis..),
        },
        {
          : ,
          : analysis..
            .( )
            .(),
        },
      ],
    };
  }
}

3. Skill Validation Engine

class SkillValidator {
  /**
   * Comprehensive skill validation
   */
  validate(skill: SkillDefinition): ValidationReport {
    const checks: ValidationCheck[] = [
      this.validateMetadata(skill),
      this.validateStructure(skill),
      this.validateContent(skill),
      this.validateExamples(skill),
      this.validateDocumentation(skill),
      this.validateSecurity(skill),
    ];

    const errors = checks.flatMap((c) => c.errors);
    const warnings = checks.flatMap((c) => c.warnings);
    const suggestions = this.generateSuggestions(skill, checks);

    return {
      valid: errors.length === 0,
      errors,
      warnings,
      suggestions,
      score: this.calculateQualityScore(checks),
    };
  }

  /**
   * Validate metadata completeness
   */
  private validateMetadata(: ):  {
     : [] = [];
     : [] = [];

     (!skill.. || skill... === ) {
      errors.();
    }

     (
      !skill.. ||
      !.(skill..)
    ) {
      errors.();
    }

     (!skill.. || skill... < ) {
      warnings.();
    }

     (!skill..) {
      errors.();
    }

     (!skill.. || skill... === ) {
      warnings.();
    }

     { errors, warnings };
  }

  
   (: ):  {
     : [] = [];
     : [] = [];

     requiredSections = [
      ,
      ,
      ,
    ];

     ( section  requiredSections) {
       (!.(skill, section)) {
        errors.();
      }
    }

     (!skill. || skill.. < ) {
      warnings.();
    }

     { errors, warnings };
  }

  
   (: ):  {
     : [] = [];

    
     placeholders = [, , , ];
     content = .(skill);

     ( placeholder  placeholders) {
       (content.(placeholder)) {
        warnings.();
      }
    }

    
     (content. < ) {
      warnings.();
    }

     { : [], warnings };
  }

  
   (: ):  {
     : [] = [];
     : [] = [];

     ( example  skill. || []) {
      
       (!.(example., skill..)) {
        errors.();
      }

      
       (!example. || example.. < ) {
        warnings.();
      }

      
       securityIssues = .(example.);
       (securityIssues. > ) {
        warnings.(
          
        );
      }
    }

     { errors, warnings };
  }

  
   (: ):  {
     : [] = [];

     (!skill.) {
      warnings.();
    }

     (!skill.) {
      warnings.();
    }

     (!skill.) {
      warnings.();
    }

     { : [], warnings };
  }

  
   (: ):  {
     : [] = [];

    
     dangerousTools = [, , ];
     tools = skill.. || [];

     ( tool  tools) {
       (dangerousTools.(tool)) {
        warnings.();
      }
    }

    
     allCode = (skill. || []).( e.).();

     secretPatterns = [
      ,
      ,
      ,
      ,
    ];

     ( pattern  secretPatterns) {
       (pattern.(allCode)) {
        warnings.();
        ;
      }
    }

     { : [], warnings };
  }

  
   (: []):  {
     totalErrors = checks.( sum + c.., );
     totalWarnings = checks.( sum + c.., );

     errorPenalty = totalErrors * ;
     warningPenalty = totalWarnings * ;

     .(,  - errorPenalty - warningPenalty);
  }
}

4. Interactive Skill Builder

class InteractiveSkillBuilder {
  /**
   * Guide user through skill creation process
   */
  async buildSkill(): Promise<SkillDefinition> {
    console.log('🎯 PCL Skill Creator - Interactive Mode\n');

    // Step 1: Domain identification
    const domain = await this.identifyDomain();
    console.log(`✓ Domain identified: ${domain.name}\n`);

    // Step 2: Knowledge extraction
    const knowledge = await this.extractKnowledge(domain);
    console.log(
      `✓ Knowledge extracted: ${knowledge.concepts.length} concepts\n`
    );

    // Step 3: Code patterns
    const patterns = await this.collectCodePatterns(domain, knowledge);
    console.log(`✓ Code patterns collected: ${patterns.length}\n`);

    // Step 4: Use cases
    const useCases = await this.defineUseCases(domain, patterns);
    console.log(`✓ Use cases defined: \n`);

    
     dependencies =  .(domain);
    .();

    
     :  = {
      domain,
      : knowledge,
      : { : patterns  },
      : .(useCases),
      dependencies,
    };

     generator =  ();
     skill = generator.(analysis);

    
     validator =  ();
     report = validator.(skill);

    .();
    .();
    .();
    .();

     (report.. > ) {
      .();
      report..( .());
    }

     (report.. > ) {
      .();
      report..( .());
    }

     (report.. > ) {
      .();
      report..( .());
    }

     skill;
  }

  
    (): <> {
    
     {
      : ,
      : ,
      : [],
      : [],
    };
  }

  
    (: ): <> {
    
     {
      : [],
      : [],
      : [],
      : [],
      : [],
    };
  }
}

Skill Templates

Minimal Skill Template

---
name: [skill-name]
version: 1.0.0
description: [Brief description]
category: [category]
tags: [tag1, tag2, tag3]
allowed-tools:
  - Read
  - Write
---

# [Skill Name] Expert

[Comprehensive description of the skill's purpose and capabilities]

## Core Concepts

### [Concept 1]

[Explanation with examples]

### [Concept 2]

[Explanation with examples]

## Code Examples

### Example 1: [Title]

```[language]
// Code example with detailed comments
```

[Explanation of the example]

Best Practices

1. [Practice 1]: [Rationale]
2. [Practice 2]: [Rationale]

Advanced Patterns

[Pattern Name]

[Description and implementation]

Troubleshooting

Issue: [Common Problem]

Solution: [Resolution steps]

References

• Official Documentation
• Community Resources

### Full-Featured Skill Template

See examples in `stdlib/ai/ai-architect-expert/SKILL.md` for comprehensive structure.

## Best Practices for Skill Creation

### 1. Domain Expertise Depth
- **Deep, not broad**: Focus on specific domain mastery
- **Practical over theoretical**: Emphasize actionable knowledge
- **Current best practices**: Keep content up-to-date
- **Real-world scenarios**: Include production-ready examples

### 2. Code Quality
- **Executable examples**: All code should be runnable
- **Comprehensive comments**: Explain non-obvious logic
- **Error handling**: Show proper error management
- **Security awareness**: No hardcoded secrets, safe patterns

### 3. Documentation Excellence
- **Clear structure**: Logical flow from basics to advanced
- **Consistent formatting**: Use standard markdown conventions
- **Complete examples**: Show full context, not just snippets
- **Cross-references**: Link to related skills and concepts

### 4. Maintainability
- **Semantic versioning**: Follow semver for versions
- **Changelog tracking**: Document changes between versions
- **Deprecation notices**: Warn about outdated patterns
- **Migration guides**: Help users upgrade

### 5. Integration Patterns
- **Dependency declaration**: Clearly state requirements
- **Composition examples**: Show skill combinations
- **Tool restrictions**: Minimal, justified allowed-tools
- **Namespace awareness**: Avoid conflicts with other skills

## Skill Quality Checklist

- [ ] Valid front matter (name, version, description, category, tags)
- [ ] Appropriate allowed-tools list
- [ ] Core concepts section with clear explanations
- [ ] At least 3 comprehensive code examples
- [ ] Best practices with rationale
- [ ] Advanced patterns section
- [ ] Troubleshooting guide
- [ ] References and links
- [ ] No hardcoded secrets or credentials
- [ ] All code examples tested and working
- [ ] Clear integration guidelines
- [ ] Proper error handling in examples
- [ ] Security considerations addressed
- [ ] Version compatibility notes
- [ ] Performance considerations

## Advanced Features

### Skill Composition Patterns

```typescript
// Example: Composite skill that combines multiple experts
const fullStackSkill = {
  name: 'fullstack-web-developer',
  composition: [
    'react-expert',      // Frontend
    'nodejs-expert',     // Backend
    'postgresql-expert', // Database
    'docker-expert',     // Deployment
    'aws-expert',        // Cloud
  ],
  coordinationStrategy: 'collaborative',
};

Dynamic Skill Loading

class SkillLoader {
  /**
   * Load skill with dependency resolution
   */
  async loadSkill(name: string): Promise<Skill> {
    const skill = await this.fetchSkill(name);
    const dependencies = skill.metadata.dependencies || [];

    // Recursively load dependencies
    const loadedDeps = await Promise.all(
      dependencies.map((dep) => this.loadSkill(dep))
    );

    return {
      ...skill,
      dependencies: loadedDeps,
    };
  }
}

Skill Versioning Strategy

interface SkillVersion {
  version: string;
  releaseDate: string;
  changes: {
    breaking: string[];
    features: string[];
    fixes: string[];
    deprecated: string[];
  };
  migrationGuide?: string;
}

// Example changelog
const changelog: SkillVersion[] = [
  {
    version: '2.0.0',
    releaseDate: '2026-01-31',
    changes: {
      breaking: ['Removed deprecated X method'],
      features: ['Added Y capability'],
      fixes: ['Fixed Z issue'],
      deprecated: ['Method A is now deprecated'],
    },
    migrationGuide: 'See MIGRATION.md for upgrade path',
  },
];

References

• PCL Language Specification
• Skill Authoring Guide
• Skill Composition Patterns
• PCL Best Practices

Related Skills

• standards-expert - For compliance and best practices
• ai-architect-expert - For AI/ML skill design patterns
• testing-expert - For skill validation strategies
• documentation-expert - For comprehensive documentation