61 lines
2.8 KiB
Markdown
61 lines
2.8 KiB
Markdown
# 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](./README.md) banner note and the
|
||
[TODO](./TODO.md) for remaining housekeeping.
|