Skill Generator

Skill Generator

Overview

Transform filtered patterns into standard SKILL.md files that any AI agent can discover and use. This is phase 3 of the assimilation pipeline—applying regularization and generating skills.

This skill combines:

1. Regularization — Filter and abstract patterns to prevent overfitting
2. Generation — Create SKILL.md files following agentskills.io spec

When to Use

Use this skill when:

• Generating skills from extracted patterns
• Creating reusable agent instructions from code analysis
• Completing the assimilation pipeline
• Converting patterns.json to SKILL.md files

Input

Required: .github/temp/patterns.json (from pattern-extractor)

Output

Primary: .github/skills/<category>/<pattern-name>/SKILL.md Mirror: .claude/skills/<category>/<pattern-name>/SKILL.md

Execution Steps

Phase A: Regularization

Step A1: Load Patterns

if [ ! -f ".github/temp/patterns.json" ]; then
    echo "ERROR: patterns.json not found. Run pattern-extractor first."
    exit 1
fi

Step A2: Apply Category Thresholds

Filter patterns based on category-specific confidence thresholds:

Action: Remove patterns below their category threshold.

Step A3: Apply Abstraction Filter

Remove repo-specific details from patterns:

Rules:

• Replace specific paths with <path> or generic patterns
• Replace variable names with <identifier> in pseudocode
• Keep pattern structure and relationships intact

Step A4: Deduplicate Patterns

Merge patterns that are functionally equivalent:

Heuristic match: Same if:

• Same category AND
• Similar name (Levenshtein distance < 3) AND
• Overlapping keywords (>50% match)

Merge strategy:

• Keep pattern with higher confidence
• Combine evidence from both
• Merge keywords (deduplicated)

Step A5: Check Registry (Optional)

If skills-index.json or skills.json exists:

1. For each pattern, check if similar skill already exists
2. Match by: name similarity + category + keywords overlap
3. If match found: Skip generation (skill already exists)
4. If no match: Proceed with generation

Step A6: Assign Status

Step A7: Save Filtered Patterns

Create .github/temp/filtered-patterns.json:

{
  "source": { ... },
  "patterns": [
    {
      "name": "...",
      "category": "...",
      "confidence": 0.85,
      "status": "validated",
      "scores": { ... },
      "evidence": [ ... ],
      "description": "...",
      "keywords": [ ... ]
    }
  ],
  "filtered_count": <original - remaining>,
  "remaining_count": <count>
}

Phase B: Skill Generation

Step B1: Create Directory Structure

# For each pattern category
mkdir -p .github/skills/architecture
mkdir -p .github/skills/reliability
mkdir -p .github/skills/quality
mkdir -p .github/skills/security
mkdir -p .github/skills/conventions

# Mirror for Claude
mkdir -p .claude/skills/architecture
mkdir -p .claude/skills/reliability
mkdir -p .claude/skills/quality
mkdir -p .claude/skills/security
mkdir -p .claude/skills/conventions

Step B2: Generate SKILL.md for Each Pattern

Use this two-part template:

---
name: <pattern-name>
description: <WHAT it does>. Use when <WHEN to use - keywords for discovery>.
metadata:
  source-repo: <original-repo>
  confidence: <0.XX>
  status: <validated|experimental>
  category: <architecture|reliability|quality|security|conventions>
  generated-at: <ISO-timestamp>
---

# <Pattern Name>

## Overview

<Abstract description of the pattern — GENERALIZABLE, not repo-specific>

---

## When to Use

Use this skill when:
- <Trigger condition as prose>
- <Another trigger>
- <Keywords embedded naturally>

---

## Pattern Structure

<Pseudocode or abstract structure — NOT repo-specific code>

```pseudocode
// Generic pattern structure
function <patternName>(<params>) {
    // Step 1: <abstract step>
    // Step 2: <abstract step>
    // Step 3: <abstract step>
}

Key Components:

• <Component 1>:
• <Component 2>:

Implementation Guide

Step 1:

Step 2:

Examples

These examples are from the source repository and show one implementation. Adapt the pattern to your project's conventions.

Source: <source-repo>

See: <file>:L<line> — See: <file>:L<line> —

Conventions

✅ Do:

❌ Don't:

Related

#### Step B3: Apply YAML Safety

Before writing SKILL.md, escape special characters in YAML frontmatter values:

**Characters that require quoting:**

| Character | Problem | Solution |
|-----------|---------|----------|
| `:` | Breaks key:value parsing | Wrap value in `"..."` |
| `#` | Starts a comment | Wrap value in `"..."` |
| `{}[]` | YAML flow syntax | Wrap value in `"..."` |
| `&*` | Anchors/aliases | Wrap value in `"..."` |
| `?|>!%@` | Special YAML chars | Wrap value in `"..."` |

**Escape rules inside double quotes:**

\ → \ (backslash first) " → " (then double quotes)

**Implementation:**

```javascript
function quoteYamlValue(value) {
  // Quote if contains special chars or starts with quote
  if (/[:#{}[\]&*?|>!%@`]/.test(value) || 
      value.startsWith("'") || 
      value.startsWith('"')) {
    return `"${escapeYamlString(value)}"`;
  }
  return value;
}

function escapeYamlString(value) {
  return value
    .replace(/\\/g, "\\\\")  // Backslashes first
    .replace(/"/g, '\\"');   // Then double quotes
}

Example:

# BAD - Will break YAML parsing
description: Use when: building APIs

# GOOD - Properly quoted
description: "Use when: building APIs"

Step B4: Write Skills to Both Locations

For each pattern:

CATEGORY="<category>"
NAME="<pattern-name>"

# Write to .github/skills
mkdir -p ".github/skills/${CATEGORY}/${NAME}"
# Write SKILL.md content (with YAML-safe frontmatter)

# Mirror to .claude/skills
mkdir -p ".claude/skills/${CATEGORY}/${NAME}"
# Copy identical content

Step B5: Generate Summary Report

After all skills generated:

✅ Skill generation complete

Generated Skills:
  architecture/
    - middleware-chain (validated, 0.92)
    - factory-pattern (validated, 0.85)
  reliability/
    - error-first-callback (validated, 0.78)
  quality/
    - arrange-act-assert (experimental, 0.72)

Summary:
  Total patterns: 12
  Filtered out: 4
  Skills generated: 8
  Validated: 6
  Experimental: 2

Locations:
  .github/skills/<category>/<pattern>/SKILL.md
  .claude/skills/<category>/<pattern>/SKILL.md

Template Details

Frontmatter (Required)

Description Field Format

The description MUST:

1. Start with what the pattern does
2. Include "Use when" trigger phrase
3. Embed discovery keywords naturally

Example:

description: Chain request handlers with next() for modular processing. Use when building middleware pipelines, adding authentication layers, or implementing request preprocessing.

Pattern Structure Section

MUST be:

• Abstract and generalizable
• Free of repo-specific paths
• Pseudocode or language-agnostic
• Focused on structure, not implementation details

❌ Don't:

// From src/middleware/auth.js
const authMiddleware = require('./auth');
app.use('/api', authMiddleware);

✅ Do:

function middleware(request, response, next) {
    // Process request
    if (condition) {
        // Handle locally
        return response.send(result);
    }
    // Pass to next handler
    next();
}

Examples Section

MUST use references, not inline code:

❌ Don't:

// Full code copied here
const express = require('express');
const app = express();
// ... 50 lines of code

✅ Do:

**Source:** `expressjs/express`

See: `lib/router/index.js:L45` — Route matching and middleware chain
See: `lib/application.js:L120` — App-level middleware registration

Error Handling

Conventions

✅ Do:

• Apply all regularization steps before generation
• Write to BOTH .github/ and .claude/ locations
• Use kebab-case for pattern names
• Include all required frontmatter fields
• Keep Pattern Structure abstract

❌ Don't:

• Include repo-specific paths in Pattern Structure
• Copy full code blocks (use references)
• Skip the status field
• Generate skills below threshold
• Organize by source repo (organize by category)

Related Skills

• repo-scanner — Phase 1: Scan repository structure
• pattern-extractor — Phase 2: Extract patterns
• orchestrator — Coordinates all phases