Skip to content

plurigrid/asi / ies/music-topos/.cursor/skills/skill-maker

Skill Maker: AI Skill Factory for Tools

Verified

Meta-skill that generates domain-specific AI skills from tool documentation

FileKindSize
SKILL.mdskill md19.0 KB
skill_maker.pyscript17.8 KB

skill_maker.py

View on GitHub
#!/usr/bin/env python3
"""
Skill Maker: AI Skill Factory for Tools
Auto-generates production-ready AI skills from tool documentation
"""

import os
import json
import re
import hashlib
import subprocess
from dataclasses import dataclass, asdict
from pathlib import Path
from datetime import datetime
from typing import List, Dict, Any, Optional
from concurrent.futures import ThreadPoolExecutor, as_completed

try:
    from anthropic import Anthropic
except ImportError:
    print("Install: pip install anthropic")
    exit(1)


# ============================================================================
# Data Structures
# ============================================================================

@dataclass
class Parameter:
    """Input/output parameter specification."""
    name: str
    type: str
    description: str
    example: Any = None


@dataclass
class Operation:
    """Tool operation specification."""
    name: str
    description: str
    inputs: List[Parameter]
    outputs: List[Parameter]
    side_effects: List[str]


@dataclass
class ToolSpec:
    """Complete tool specification."""
    name: str
    description: str
    language: str
    operations: List[Operation]
    inputs: List[Parameter]
    outputs: List[Parameter]
    examples: List[str]
    urls: List[str]
    deterministic: bool = False
    parallelizable: bool = False


# ============================================================================
# Phase 1: Tool Discovery
# ============================================================================

class ToolDiscovery:
    """Discover tool specifications via web search."""

    def __init__(self):
        self.client = Anthropic()

    def discover_tool(self, tool_name: str) -> ToolSpec:
        """
        Discover tool specification using Claude's knowledge.
        (In production, would use Firecrawl for web scraping)
        """
        print(f"πŸ” Discovering {tool_name}...")

        prompt = f"""
Provide a detailed technical specification for the tool: {tool_name}

Format response as JSON:
{{
    "name": "{tool_name}",
    "description": "Brief description",
    "language": "primary language (Python/Rust/etc)",
    "operations": [
        {{
            "name": "operation_name",
            "description": "what it does",
            "inputs": [{{"name": "param", "type": "type", "description": "desc"}}],
            "outputs": [{{"name": "output", "type": "type", "description": "desc"}}],
            "side_effects": []
        }}
    ],
    "examples": ["example 1", "example 2"],
    "urls": ["documentation_url"],
    "deterministic": true/false,
    "parallelizable": true/false
}}
"""

        response = self.client.messages.create(
            model="claude-opus-4-5-20251101",
            max_tokens=2000,
            messages=[{"role": "user", "content": prompt}]
        )

        # Parse response
        try:
            spec_json = json.loads(response.content[0].text)
        except json.JSONDecodeError:
            # Extract JSON from response
            match = re.search(r'\{.*\}', response.content[0].text, re.DOTALL)
            if match:
                spec_json = json.loads(match.group())
            else:
                raise ValueError(f"Could not parse tool spec for {tool_name}")

        # Convert to ToolSpec
        ops = [
            Operation(
                name=op["name"],
                description=op["description"],
                inputs=[Parameter(**p) for p in op.get("inputs", [])],
                outputs=[Parameter(**p) for p in op.get("outputs", [])],
                side_effects=op.get("side_effects", [])
            )
            for op in spec_json.get("operations", [])
        ]

        return ToolSpec(
            name=spec_json["name"],
            description=spec_json["description"],
            language=spec_json.get("language", "Python"),
            operations=ops,
            inputs=spec_json.get("inputs", []),
            outputs=spec_json.get("outputs", []),
            examples=spec_json.get("examples", []),
            urls=spec_json.get("urls", []),
            deterministic=spec_json.get("deterministic", False),
            parallelizable=spec_json.get("parallelizable", False)
        )


# ============================================================================
# Phase 2: Pattern Recognition
# ============================================================================

class PatternRecognizer:
    """Analyze tool semantics for SPI opportunities."""

    def __init__(self):
        self.client = Anthropic()

    def analyze_tool_semantics(self, tool_spec: ToolSpec) -> Dict[str, Any]:
        """Use Claude to understand tool semantics."""
        print(f"🧠 Analyzing patterns for {tool_spec.name}...")

        prompt = f"""
Analyze this tool and identify how to make it deterministic with SplitMix seeding:

Tool: {tool_spec.name}
Description: {tool_spec.description}
Language: {tool_spec.language}

Operations:
{json.dumps([asdict(op) for op in tool_spec.operations[:3]], indent=2)}

Respond with JSON:
{{
    "deterministic_feasible": true/false,
    "parallelizable": true/false,
    "seeding_strategy": "file_order|timestamp|hash_input|rng_state|default",
    "polarity_classification": {{
        "+1": {{"name": "Positive", "indicators": ["keyword1", "keyword2"]}},
        "0": {{"name": "Neutral", "indicators": ["keyword3", "keyword4"]}},
        "-1": {{"name": "Negative", "indicators": ["keyword5", "keyword6"]}}
    }},
    "parallel_strategy": "work-stealing|map-reduce|pipeline|default",
    "key_operations": ["op1", "op2"],
    "determinism_principle": "Brief explanation",
    "github_url": "https://github.com/..."
}}
"""

        response = self.client.messages.create(
            model="claude-opus-4-5-20251101",
            max_tokens=1500,
            messages=[{"role": "user", "content": prompt}]
        )

        try:
            return json.loads(response.content[0].text)
        except json.JSONDecodeError:
            match = re.search(r'\{.*\}', response.content[0].text, re.DOTALL)
            if match:
                return json.loads(match.group())
            raise


# ============================================================================
# Phase 3-5: Code Generation
# ============================================================================

class SkillCodeGenerator:
    """Generate seeding, polarity, and parallel code."""

    @staticmethod
    def generate_seeding_code(tool_spec: ToolSpec, strategy: str) -> str:
        """Generate SplitMix-based seeding code."""
        return f"""
# SplitMix64 Seeding Strategy for {tool_spec.name}

class SplitMix64:
    PHI_INV = 0x9E3779B97F4A7C15

    def __init__(self, seed: int):
        self.state = seed & 0xFFFFFFFFFFFFFFFF

    def next_u64(self) -> int:
        z = ((self.state ^ (self.state >> 30)) * 0xBF58476D1CE4E5B9) & 0xFFFFFFFFFFFFFFFF
        self.state = (self.state + self.PHI_INV) & 0xFFFFFFFFFFFFFFFF
        return z ^ (z >> 27)

    def next_u32(self) -> int:
        return (self.next_u64() >> 32) & 0xFFFFFFFF


class {tool_spec.name}Deterministic:
    def __init__(self, seed: int):
        self.seed = seed
        self.rng = SplitMix64(seed)

    def process_deterministic(self, input_data):
        '''Process with deterministic ordering via SplitMix seeding.'''
        # Seed all non-deterministic sources
        result = {tool_spec.operations[0].name if tool_spec.operations else 'process'}(
            input_data,
            seed=self.seed
        )
        return result
"""

    @staticmethod
    def generate_polarity_code(tool_spec: ToolSpec, classification: Dict) -> str:
        """Generate GF(3) polarity classifier."""
        return f"""
# GF(3) Polarity Classification for {tool_spec.name}

class {tool_spec.name}PolarityClassifier:
    def classify(self, output) -> int:
        '''Classify output to GF(3) trit: -1 (negative), 0 (neutral), +1 (positive).'''
        output_str = str(output).lower()

        # Positive indicators
        if any(kw in output_str for kw in {classification.get("+1", {}).get("indicators", [])}):
            return +1

        # Negative indicators
        if any(kw in output_str for kw in {classification.get("-1", {}).get("indicators", [])}):
            return -1

        # Neutral default
        return 0
"""

    @staticmethod
    def generate_parallel_code(tool_spec: ToolSpec) -> str:
        """Generate parallel execution code."""
        return f"""
# Parallel Execution for {tool_spec.name}

class {tool_spec.name}Parallel:
    def __init__(self, n_workers: int, seed: int):
        self.n_workers = n_workers
        self.seed = seed
        self.worker_seeds = self._split_seeds()

    def _split_seeds(self) -> List[int]:
        '''Generate independent seeds for each worker.'''
        rng = SplitMix64(self.seed)
        return [rng.next_u64() for _ in range(self.n_workers)]

    def process_parallel(self, items: List):
        '''Process items in parallel with deterministic ordering.'''
        from concurrent.futures import ThreadPoolExecutor, as_completed

        results = []

        with ThreadPoolExecutor(max_workers=self.n_workers) as executor:
            # Distribute items to workers
            futures = []
            for worker_id in range(self.n_workers):
                worker_items = items[worker_id::self.n_workers]
                future = executor.submit(
                    self._process_worker,
                    worker_items,
                    self.worker_seeds[worker_id]
                )
                futures.append(future)

            # Collect results
            for future in as_completed(futures):
                results.extend(future.result())

        # Sort deterministically
        return sorted(results, key=lambda x: str(x))

    def _process_worker(self, items, seed):
        '''Process subset with given seed.'''
        return [{tool_spec.operations[0].name if tool_spec.operations else 'process'}(item) for item in items]
"""


# ============================================================================
# Phase 6: SKILL.md Generation
# ============================================================================

class SkillMarkdownGenerator:
    """Generate complete SKILL.md file."""

    HEADER_TEMPLATE = """---
name: "{tool_name_pretty}: Deterministic {description_short}"
description: "{description_full}"
status: "Generated by Skill Maker"
trit: "{trit}"
principle: "Same seed + same input β†’ same output (SPI guarantee)"
---

# {tool_name_pretty} AI Skill

**Version:** 1.0.0
**Status:** Generated {timestamp}
**Trit:** {trit} ({trit_meaning})
**Principle:** {determinism_principle}

## Overview

This AI skill enhances {tool_name} with deterministic, parallelizable analysis:

{overview_bullets}

## Core Properties

βœ… **Deterministic:** Same seed guarantees identical results
βœ… **Parallel-Safe:** Work-stealing without conflicts
βœ… **Ternary-Classified:** Outputs map to GF(3) = {{-1, 0, +1}}
βœ… **SPI Guarantee:** Split-stream execution is order-independent

## Architecture

```
{tool_name} AI Skill
β”œβ”€ SplitMix64 Seeding (deterministic entropy)
β”œβ”€ Ternary Polarity (GF(3) classification)
β”œβ”€ Work-Stealing Parallelism
└─ MCP Integration
```

## SplitMix64 Seeding

{seeding_code}

## Ternary Polarity Classification

{polarity_code}

## Parallel Execution

{parallel_code}

## Usage with Claude Code

```bash
# Run {tool_name} with deterministic seed
claude code --skill {tool_name_lower} --prompt "
Analyze with seed 0xDEADBEEF (fixed for reproducibility)
"

# Same seed = same results across team
export {tool_name_upper}_SEED=0xCAFEBABE
```

## Properties Guaranteed

### Determinism
```
βˆ€ input I, seed S:
  process(I, S) = process(I, S)  [always identical]
```

### Out-of-Order Invariance
```
βˆ€ input I, seed S, permutation Ο€:
  sort(process(I, S)) = sort(process_reordered(I, S, Ο€))
```

### Ternary Conservation
```
βˆ€ results R:
  #(R with trit +1) + #(R with trit 0) + #(R with trit -1)
  ≑ |R| (mod GF(3))
```

---

**Generated:** {timestamp}
**Tool:** {tool_name}
**Source:** {github_url}

"""

    @staticmethod
    def assign_trit(tool_spec: ToolSpec) -> tuple:
        """Assign +1, 0, or -1 based on operations."""
        ops = [o.name.lower() for o in tool_spec.operations]

        positive_kws = ['add', 'create', 'generate', 'insert', 'build', 'scan', 'find']
        negative_kws = ['remove', 'delete', 'filter', 'strip', 'clean']

        pos_count = sum(1 for kw in positive_kws for o in ops if kw in o)
        neg_count = sum(1 for kw in negative_kws for o in ops if kw in o)

        if pos_count > neg_count:
            return "+1", "Generative - adds/finds/creates"
        elif neg_count > pos_count:
            return "-1", "Reductive - removes/filters/eliminates"
        else:
            return "0", "Neutral - analyzes/transforms/structures"

    @classmethod
    def generate_skill_md(
        cls,
        tool_spec: ToolSpec,
        pattern_analysis: Dict,
        seeding_code: str,
        polarity_code: str,
        parallel_code: str
    ) -> str:
        """Generate complete SKILL.md."""
        print(f"πŸ“ Generating SKILL.md for {tool_spec.name}...")

        trit, trit_meaning = cls.assign_trit(tool_spec)

        overview = "\n".join([
            f"- **{op.name}:** {op.description}"
            for op in tool_spec.operations[:5]
        ])

        skill_md = cls.HEADER_TEMPLATE.format(
            tool_name=tool_spec.name,
            tool_name_pretty=tool_spec.name.title(),
            tool_name_lower=tool_spec.name.lower(),
            tool_name_upper=tool_spec.name.upper(),
            description_short=tool_spec.description.split('\n')[0][:50],
            description_full=tool_spec.description,
            timestamp=datetime.now().isoformat(),
            trit=trit,
            trit_meaning=trit_meaning,
            determinism_principle=pattern_analysis.get(
                "determinism_principle",
                "Deterministic analysis with SplitMix64 seeding"
            ),
            overview_bullets=overview,
            seeding_code=seeding_code,
            polarity_code=polarity_code,
            parallel_code=parallel_code,
            github_url=pattern_analysis.get("github_url", "https://github.com/..."),
        )

        return skill_md


# ============================================================================
# Phase 7: Deployment
# ============================================================================

class MCPDeployer:
    """Register skill with Claude Code."""

    @staticmethod
    def deploy_skill(skill_md: str, tool_name: str) -> bool:
        """Deploy generated skill."""
        print(f"πŸš€ Deploying {tool_name} skill...")

        skill_dir = Path.home() / ".cursor" / "skills" / tool_name.lower()
        skill_dir.mkdir(parents=True, exist_ok=True)

        # Write SKILL.md
        skill_file = skill_dir / "SKILL.md"
        skill_file.write_text(skill_md)
        print(f"   βœ“ Created {skill_file}")

        # Try to register
        try:
            result = subprocess.run(
                ["claude", "code", "--register-skill", tool_name.lower()],
                capture_output=True,
                text=True,
                timeout=10
            )
            if result.returncode == 0:
                print(f"   βœ“ Registered {tool_name.lower()} skill")
                return True
            else:
                print(f"   ⚠ Registration warning: {result.stderr[:100]}")
                # Still success - skill file is created
                return True
        except Exception as e:
            print(f"   ⚠ Could not register: {e}")
            # Still success - skill file is created
            return True


# ============================================================================
# Main Pipeline
# ============================================================================

def make_skill_for_tool(tool_name: str) -> bool:
    """
    Complete pipeline: discover β†’ analyze β†’ generate β†’ deploy skill.
    """
    print(f"\n🎯 Creating AI skill for: {tool_name}")
    print("=" * 60)

    try:
        # Phase 1: Discovery
        discoverer = ToolDiscovery()
        tool_spec = discoverer.discover_tool(tool_name)

        # Phase 2: Pattern Analysis
        analyzer = PatternRecognizer()
        pattern_analysis = analyzer.analyze_tool_semantics(tool_spec)

        # Phases 3-5: Code Generation
        generator = SkillCodeGenerator()
        seeding_code = generator.generate_seeding_code(
            tool_spec,
            pattern_analysis.get("seeding_strategy", "default")
        )
        polarity_code = generator.generate_polarity_code(
            tool_spec,
            pattern_analysis.get("polarity_classification", {})
        )
        parallel_code = generator.generate_parallel_code(tool_spec)

        # Phase 6: SKILL.md Generation
        md_generator = SkillMarkdownGenerator()
        skill_md = md_generator.generate_skill_md(
            tool_spec,
            pattern_analysis,
            seeding_code,
            polarity_code,
            parallel_code
        )

        # Phase 7: Deployment
        deployer = MCPDeployer()
        success = deployer.deploy_skill(skill_md, tool_name)

        if success:
            print(f"\nβœ… Success! {tool_name} skill is ready")
            print(f"   Location: ~/.cursor/skills/{tool_name.lower()}/SKILL.md")
            print(f"   Usage: claude code --skill {tool_name.lower()}")
        else:
            print(f"\n❌ Failed to deploy {tool_name} skill")

        return success

    except Exception as e:
        print(f"\n❌ Error creating skill: {e}")
        import traceback
        traceback.print_exc()
        return False


if __name__ == "__main__":
    import sys

    if len(sys.argv) < 2:
        print("Usage: skill_maker.py <tool_name> [tool_name2 ...]")
        print("Example: skill_maker.py cq ripgrep")
        sys.exit(1)

    # Create skills for all specified tools
    for tool_name in sys.argv[1:]:
        make_skill_for_tool(tool_name)
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product β€” it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product β€” not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial β€” a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK β€” model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER β€” read BEFORE opening the target file; don't skip because it "looks like a one-liner" β€” whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) β€” never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named β€” don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.Stars: 198kUpdated Claude CodeCodexVerifiedInstall