claude-code-meta-skill/ARCHITECTURE.md

Architecture Notes — Meta Skill Generator

This document captures the design evolution behind this repository as a reference for how thinking about coding-agent skill architectures has progressed.

Original Concept (Nov 2025 — This Repo)

Toolchain: Claude Code (Anthropic) — skills packaged as .skill ZIP files

Core insight: Separate deterministic operations from agent reasoning. The meta-skill generator analyzes user requirements and classifies each operation into one of three buckets:

Bucket	Technology	When
Deterministic scripts	Compiled Go binaries	Format conversion, batch processing, file I/O
Library-heavy scripts	Python scripts	pandas, ML, visualization
Agent workflows	Natural language in SKILL.md	Analysis, reasoning, creative tasks

Why Go? The argument was: compiled binaries are fast, have no runtime dependencies, and are good for things like PDF conversion or CSV processing that don't need LLM reasoning.

Pain points discovered:

• Go scripts are external processes — startup latency, IPC overhead
• Debugging requires attaching to a separate process
• Maintaining Go toolchain for what are often small utilities
• The .skill ZIP format is opaque — easy to lose the source

Evolution (Current Thinking)

Toolchain: Pi.dev — extensions (in-process plugins), stored prompts, skills

The same core insight holds (separate deterministic ops from reasoning), but the implementation has shifted:

Component	Now	Benefit
Deterministic operations	Pi.dev extensions (TypeScript/JS)	In-process with the agent, ~10× faster than shell scripts, immediate stack traces, "let it crash" debugging
Prompts / instructions	Stored prompt templates	Referenced by name, versioned separately from code
Orchestration	Conversational prompting	More fluid, adaptive to context

Key realisations:

• Extensions running in the same process as the agent give you crashes, stack traces, and debugging right there instead of having to chase a subprocess.
• The boundary between "code" and "prompt" is blurrier than the original strict three-bucket model suggested. Sometimes you want a prompt that references a plugin; sometimes a plugin that calls back to the agent.
• The .skill → ZIP pattern works but adds friction. Flat source + a tool that knows how to load it is simpler.

Summary

This repo represents an early, structured take on a problem that's still relevant: not everything needs an LLM, and not everything needs a subprocess. The current approach (Pi.dev extensions + stored prompts) achieves the same separation with less overhead and tighter integration.

See also the README banner note and the TODO for remaining housekeeping.