Amplifier Skills

The Meta-Skill

How to create template-based Amplifier skills — a methodology extracted from building scaffold-new-service

Feb 13 – Mar 4, 2026 Active Methodology
The Problem

Copy, paste, forget, debug.

Repetitive Scaffolding

Every new FastAPI microservice required the same boilerplate: project structure, auth middleware, Docker config, frontend setup, CI scripts.

Tribal Knowledge

The right way to stand up a service lived in the developer’s head and in scattered reference implementations — not in any teachable artifact.

Time Sink

Each new service was built by hand. Same patterns, same mistakes, same debugging session every time.

Act 1 · Feb 13

Genesis: “Transfer over all the scaffolding”

“I want to create a new skill that stands up a new service… Make sure ALL the changes needed are captured.”
— The user, recognizing the pattern after building 3 services by hand

The key insight: don’t design a skill in a vacuum. Build real things first, then extract the reusable pattern. The user had lived through the pain of manual scaffolding three times — enough to know what should be automated.

Act 1 · The Process

Explore, Decide, Ship V1

Explore

The AI read every file in two reference services in parallel, mapping project structure, config patterns, middleware chains, and deployment scripts.

Inventory & Ask

Produced a full artifact list, then asked 6 design questions before writing anything: auth optional or required? Templates or instructions? Monorepo or standalone?

Result: V1

A single SKILL.md — 365 lines, 11 sections. Pure instructions referencing live files in gh-issues-local/. Deliberately minimal.

The Hidden Fragility

The skill didn’t contain the knowledge — it contained pointers to the knowledge. Every section said: “See gh-issues-local/src/app.py for reference.” Those pointers assumed gh-issues-local would always exist, unchanged, in the same location.

Act 2 · Feb 17 – Mar 3

The Proving Ground

Feb 17
✓ First real test: nl-spec-generator
Four days after creation, the skill got its first use. A new service scaffolded by the AI following the SKILL.md instructions. Validation passed.
Feb–Mar
Workspace evolves
Infrastructure shifted: github-local was retired, Gitea replaced it. Services were refactored, moved, renamed. The codebase was a moving target.
Mar 3
✗ ~30 references break
During the Gitea migration, the AI discovered ~30 stale references in SKILL.md — all pointing to the now-retired gh-issues-local. Every “see gh-issues-local/…” instruction was a dead link.
Act 3 · Mar 4

The Pivot: Self-Contained Templates

“Come up with a plan to store sample files in that directory, so we are not reliant on any service.”
— The user, articulating the core insight

AI’s Response

Proposed 26 template files with placeholder tokens. Extracted from issues-to-brief (backend) and recovered from the retired github-local’s git cache (frontend). Even dead code was resurrected as reusable templates.

Same-Day Validation

Hours after the V2 conversion, the template skill was used to build The Garden’s web frontend. The AI loaded the skill, read templates from templates/web/, and used them as the foundation. It worked immediately.

Act 3 · The Mechanism

Placeholder Tokens as Abstraction Layer

# pyproject.toml template [project] name = "{{PACKAGE_NAME}}" version = "0.1.0" [project.scripts] start = "{{PACKAGE_NAME}}.app:main" # vite.config.ts template export default defineConfig({ server: { port: {{PORT_BASE_PLUS_1}}, proxy: { '/api': 'http://localhost:{{PORT_BASE}}' } } })

{{SERVICE_NAME}}

Directory name, display strings

{{PACKAGE_NAME}}

Python package, imports

{{PORT_BASE}}

Backend port, frontend proxy

The Evolution

V1 → V2: From Pointers to Packages

V1 Feb 13
scaffold-new-service/ \-- SKILL.md (365 lines) References → gh-issues-local/ "See gh-issues-local/src/app.py" "See gh-issues-local/pyproject.toml" ✗ Fragile: depends on external code ✗ ~30 stale pointers after migration
V2 Mar 4
scaffold-new-service/ +-- SKILL.md (255 lines, more concise) \-- templates/ +-- pyproject.toml +-- src/app.py +-- src/auth.py +-- scripts/smoke_test.py +-- web/package.json +-- web/vite.config.ts \-- ... (26 files total) ✓ Self-contained, portable & parameterized
The Repeatable Process

The Meta-Methodology

01
Build First, Extract Later
Don’t design skills in the abstract. Build something real by hand, then look back and ask “what’s the reusable pattern here?” The skill was extracted from 3 real services — not designed top-down.
02
AI as Pattern Miner
Ask the AI to explore existing implementations and propose what a generalized skill should contain. It reads every file, produces artifact inventories, and asks clarifying questions.
03
Human Directs, AI Executes
The AI proposes options; the human makes architectural choices. “Pure instructions vs. templates” was a human call. “Auth is optional” was a human call. Design decisions stay human-driven.
04
Start Minimal, Upgrade When Pain Emerges
V1 was deliberately minimal. Only when references broke did the user invest in templates. The upgrade wasn’t premature — it was motivated by a real failure mode.
05
Self-Contained > Cross-References
Bundle template files with {{PLACEHOLDER}} tokens so the skill is independent of any service’s existence. Skills that reference live code are fragile; skills that carry their own templates are not.
06
Validate Immediately
Use the skill right away on a real task. V1 was validated 4 days later on nl-spec-generator. V2 was validated the same evening on The Garden. If it doesn’t work in practice, iterate.
Skill Structure

Anatomy of an Amplifier Skill

Skills follow the Agent Skills specification. The directory name must match the name field in SKILL.md. Here’s the standard structure and how scaffold-new-service maps to it.

Standard Skill Structure my-skill/ SKILL.md # Required: frontmatter + instructions references/ # Optional: additional docs assets/ # Optional: templates, data files scripts/ # Optional: executable code --- SKILL.md frontmatter --- name: my-skill description: Apply X when Y happens --- # Then markdown body: steps, examples, # templates, edge cases
scaffold-new-service (V2) scaffold-new-service/ SKILL.md # 255 lines, 11 steps templates/ # 26 files (= assets) pyproject.toml # {{PACKAGE_NAME}} src/app.py # FastAPI factory src/auth.py # Bearer middleware web/ # React + Vite frontend scripts/ # smoke_test.py ... # SKILL.md uses read_file(skill_directory # + "/templates/foo") to load templates
Skill Structure

Writing an Effective SKILL.md

YAML

Frontmatter: name + description

The description is critical — it’s how the agent decides whether to load your skill. Write triggering conditions, not a workflow summary.

✗ “Scaffolds a new FastAPI service with auth”
✓ “Use when standing up a new service in this workspace”
MD

Body: Steps + Tokens + Branches

Start with an overview and a placeholder token table. Then numbered steps the agent follows in order. Include conditional branches (e.g. “if auth requested”, “if web UI requested”) and edge cases.

REF

Companion Files: Templates & Assets

Heavy content goes in separate files. Keep the main SKILL.md scannable (<500 lines). The agent loads companions on demand via read_file(skill_directory + “/templates/foo”).

Amplifier vs Claude.ai

Both follow the same Agent Skills specification. Amplifier skills live in .amplifier/skills/ (project) or ~/.amplifier/skills/ (global), are discovered via load_skill(), and can be bundled with tool-skills config. Claude.ai skills are uploaded as ZIP files with descriptions capped at 200 chars and support declared pip/npm script dependencies in frontmatter.

The Punchline

This process is itself a skill.

The methodology for creating template-based skills — build, extract, mine, decide, validate, harden — is a repeatable, teachable pattern. Which is exactly what a skill is.

Try the Process

1. Build something real by hand, at least twice

2. Ask the AI to mine the pattern

3. Make the design decisions yourself

4. Start with instructions, upgrade to templates when the pain demands it

5. Validate immediately on a new project

More Amplifier Stories