Getting Started with GSD + Skill Creator

What Problem Does This Solve?

AI coding assistants like Claude Code are powerful in short bursts. Ask them to build a login page and they'll do it well. But as your project grows — hundreds of files, multi-day builds, architectural decisions made three sessions ago — things fall apart in three predictable ways:

Context rot. Claude's context window fills up as a session goes on. By the time you're deep into implementation, it's forgotten the architectural choices you made two hours ago. Quality degrades steadily, and you start seeing contradictions and repeated mistakes.

Amnesia between sessions. Every time you start a new conversation, Claude starts from zero. It doesn't know what worked last time, what coding patterns you prefer, or what you explicitly told it to avoid three days ago.

No workflow memory. You always run lint, then test, then fix. You always check fixture data first after a test failure. Claude never learns these patterns. You re-explain them every single time.

GSD and Skill Creator are two systems that solve these problems together. GSD prevents the AI from degrading during work. Skill Creator prevents the AI from forgetting between work.

The Three Layers: Claude Code, GSD, and Skill Creator

Think of these as three levels of capability stacked on top of each other. Each one works on its own, but they get dramatically more powerful in combination.

You don't need all three from day one. Many people start with just GSD on top of Claude Code and that alone is a huge improvement. Skill Creator becomes valuable when you start doing recurring work and want the system to get better over time.

Five Users, Five Starting Points

This guide walks through five different people with five different levels of experience and clarity. Find the one closest to you and start there — but reading the earlier ones will build your understanding of how each layer adds value.

Installation in 60 Seconds

Step 1: Install GSD

npx get-shit-done-cc@latest

The installer will ask you which runtime (Claude Code, OpenCode, Gemini, or all) and whether to install globally (all projects) or locally (this project only). If you're not sure, pick Claude Code and global.

Step 2: Install Skill Creator

git clone https://github.com/Tibsfox/gsd-skill-creator.git
cd gsd-skill-creator
npm install
npm run build
npm link  # makes 'skill-creator' available everywhere

Step 3: Verify

# Inside Claude Code:
/gsd:help              # Should show GSD commands

# In your terminal:
skill-creator help    # Should show Skill Creator commands

Scenario 1 — Total Beginner, No Idea

Alex has never built anything. They just want to explore. Here's what each layer looks like for Alex.

Claude Code Alone

Alex opens Claude Code and types: "I want to build something cool." Claude will write code — probably a random project like a to-do app. It'll work for the first few minutes. Then Alex asks for changes, Claude makes them, context fills up, and things start breaking. Alex starts a new session, and Claude has no memory of what they built. Alex re-explains everything. Gets frustrated. Quits.

With GSD Added

Alex types /gsd:new-project. Instead of immediately writing code, GSD asks questions:

• "What do you want to build?" — I don't know, maybe something with recipes?
• "Who is it for?" — Just me, I cook a lot.
• "What's most important?" — I want to save my own recipes and search them.

GSD keeps asking until it has a clear picture. Then it creates a document called PROJECT.md with the vision, REQUIREMENTS.md with what's v1 vs. v2, and a ROADMAP.md that breaks it into small phases like "Phase 1: Basic recipe storage" and "Phase 2: Search and categories."

Each phase gets planned, executed in a fresh context window (no rot), committed to git, and verified. Alex comes back the next day, types /gsd:resume-work, and GSD picks up exactly where they left off because it keeps state in STATE.md.

With Skill Creator Added on Top

Over the first week, Alex keeps working on the recipe app. Skill Creator is quietly watching. It notices patterns:

• Alex always asks Claude to use Tailwind CSS.
• Alex always runs npm run dev after every code change.
• Alex always wants components to look "clean and simple."

After 3+ repetitions, Skill Creator surfaces a suggestion: "I've noticed you always use Tailwind with a minimal aesthetic. Want me to create a skill for this so it's automatic?" Alex says yes. Now a Markdown file called alex-frontend-style/SKILL.md lives in .claude/skills/, and the next time Alex starts a project, Claude automatically knows their preferences without being told.

This is the simplest version of what Skill Creator does: it watches, it learns, it captures knowledge so you don't have to repeat yourself.

Scenario 2 — Some Experience, Rough Idea

Sam has built a few things but they always fall apart as they get bigger. Sam wants a habit tracker but the details are fuzzy.

Claude Code Alone

Sam says "build me a habit tracker." Claude scaffolds a React app, builds some components, and it looks good for the first 30 minutes. Then Sam asks for streaks, notifications, and a calendar view. By the time Sam is asking for the fifth feature, Claude has forgotten the data model it created and starts contradicting its own earlier decisions. Sam manually copies important info into each new chat.

With GSD

Sam runs /gsd:new-project. GSD's question phase draws out the requirements Sam didn't realize they had: Do streaks reset on weekdays only? What happens when you miss a day? Mobile or desktop? The research phase investigates habit-tracking patterns and suggests a data model.

When it's time to build Phase 1, Sam runs /gsd:discuss-phase 1. This is where Sam shapes things before code is written: "I want the habit list to feel like iOS, not Material Design." These preferences get captured in CONTEXT.md, which feeds into planning and execution.

Each phase gets fresh context. Claude never accumulates enough conversation history to degrade. And each task gets its own atomic git commit, so if something breaks, Sam can revert just that one task.

With Skill Creator

After a few projects, Sam has built up a personal skill library:

• react-conventions — Sam's preferred component patterns and naming conventions
• supabase-auth — Sam always uses Supabase for auth, and this skill contains the setup steps
• ios-aesthetic — The visual preferences Sam described during discuss-phase, now captured permanently

These skills auto-load based on context. When Sam starts a new project with React, the react-conventions skill activates automatically within a small token budget (2–5% of context). Sam never tells Claude about these preferences again. They just work.

If Skill Creator notices that react-conventions and supabase-auth always activate together (5+ times over 7+ days), it suggests composing them into an agent called react-fullstack-agent — a composite that bundles both skills' knowledge into a single unit Claude can delegate to.

Scenario 3 — Competent Dev, Clear Spec

Jordan knows exactly what they want: a REST API with JWT auth, rate limiting, PostgreSQL, and a React admin dashboard. They want Claude to execute it reliably.

Claude Code Alone

Jordan pastes a spec and says "build this." Claude starts strong. But by the time it's wiring the rate limiter to the auth middleware, it's lost track of the database schema it created 40 messages ago. Jordan spends as much time correcting Claude as they would have spent coding it themselves.

With GSD

Jordan runs /gsd:new-project. Because Jordan already has a clear spec, the question phase is fast. GSD creates a tight roadmap: Phase 1 (database + models), Phase 2 (auth + middleware), Phase 3 (API endpoints), Phase 4 (admin dashboard), Phase 5 (rate limiting + monitoring).

During /gsd:plan-phase 1, GSD spawns parallel research agents to investigate the best PostgreSQL driver for their Node version, the optimal schema design for their data model, and potential pitfalls. Then it creates 2–3 atomic task plans per phase, each with XML structure and built-in verification steps:

<task type="auto">
  <n>Create users table migration</n>
  <files>src/db/migrations/001_create_users.ts</files>
  <action>Use drizzle-orm. Include email (unique), password_hash,
    created_at, updated_at. Add index on email.</action>
  <verify>Run migration, check table exists with
    correct columns</verify>
  <done>Users table created with email index</done>
</task>

During execution, each task gets its own fresh 200K token context window. No accumulated garbage. Every task gets its own git commit. Jordan runs /gsd:verify-work 1 and GSD walks them through testable deliverables: "Can you query the users table? Does the migration roll back cleanly?" If something fails, GSD spawns debug agents to diagnose and creates fix plans.

With Skill Creator

Jordan creates skills proactively for their team's standards:

skill-creator create

They create a skill called team-api-conventions that documents their company's API style: always use snake_case in JSON, always return envelope responses, always include request IDs. Now every project Jordan starts automatically follows these conventions without a lengthy system prompt.

Jordan also creates skills for their testing patterns, their deployment pipeline, and their error handling approach. These compose into an agent called backend-engineer that bundles everything together.

Scenario 4 — Pro Developer, Complex System

Morgan is building a platform with 20+ microservices. They need consistency, shared patterns, and the ability to onboard Claude to their company's engineering culture.

GSD at Scale

Morgan uses GSD's milestone system. Each microservice is a milestone with its own lifecycle:

/gsd:new-project          # Service 1: user-service
... discuss, plan, execute, verify for each phase ...
/gsd:complete-milestone
/gsd:new-milestone        # Service 2: billing-service

The /gsd:map-codebase command spawns parallel agents to analyze the existing codebase before starting a new milestone. This means when Morgan starts the billing service, GSD already knows the patterns established in the user service — it won't contradict them.

Skill Creator at Scale

Morgan builds a layered skill library:

• User-level skills (~/.claude/skills/) — Morgan's personal coding style, shared across all projects
• Project-level skills (.claude/skills/) — Project-specific conventions that override personal ones when needed

The team's shared skills cover:

• Database migration patterns
• gRPC service definitions
• Error code conventions (every service uses the same error taxonomy)
• Observability standards (how to instrument traces, metrics, and logs)

When Skill Creator detects that the database, error-handling, and observability skills always activate together for backend work, it suggests composing them into a backend-platform-agent. Morgan approves, and now every new microservice gets that bundled expertise automatically.

Agent Teams

Morgan goes further and creates teams — multi-agent configurations with specific topologies:

• Pipeline topology: Code flows from planner → implementer → reviewer → tester, each agent specialized
• Leader-worker topology: One orchestrator agent delegates to worker agents
• Swarm topology: Multiple agents work independently on different services in parallel

Skill Creator manages the coordination, ensuring agents don't step on each other's work and that shared state is consistent.

Scenario 5 — Architect, Multi-Agent Orchestration

River wants to push the system to its limits. They want specialized agent teams, custom chipset configurations, and educational packs for onboarding new team members. This is where Skill Creator's deepest features come into play, and we'll spend more time on it in the sections that follow.

River's workflow combines everything:

1. GSD manages the project lifecycle (phases, milestones, verification)
2. Skills capture domain knowledge (React patterns, their API spec, security requirements)
3. Agents compose skills into specialized roles (frontend-agent, backend-agent, security-agent)
4. Teams coordinate agents into topologies (the frontend and backend agents work in a pipeline; the security agent reviews everything)
5. Chipset YAML configures the entire system — skills, agents, teams, token budgets, and routing — in a single declarative file
6. Knowledge Packs provide structured educational content for onboarding, domain learning, or curriculum delivery

The rest of this guide explains these deeper concepts in detail.

The Key Difference, Summarized

Skills: The Building Blocks

A skill is a Markdown file with some metadata at the top. That's it. It's a document that tells Claude how to handle a specific domain, pattern, or convention. Skills live in .claude/skills/ and look like this:

---
name: git-commit-workflow
description: Guides structured git commits with conventional
  format. Use when committing changes or writing commit messages.
---

## Conventional Commit Format

Structure: `type(scope): description`

Types: feat, fix, docs, style, refactor, test, chore

### Rules
- Subject line under 50 characters
- Body wrapped at 72 characters
- Reference issue numbers when applicable

The description field is crucial. It's what Claude reads to decide whether to activate this skill automatically. Good descriptions include a "Use when..." clause with specific keywords users would actually type.

How Skills Activate

When you're working in Claude Code, Skill Creator runs a 6-stage loading pipeline behind the scenes:

It scores every skill against your current context, resolves conflicts and inheritance, filters by model, orders by cache priority, fits within the token budget (2–5% of context), and loads the winners. You never manage this manually. It just works.

Two Scopes

User-level skills live in ~/.claude/skills/ and follow you across every project. Your personal coding style, your preferred tools, your formatting preferences — put them here.

Project-level skills live in .claude/skills/ inside a specific project. When the same skill name exists at both levels, the project version wins. This lets you have personal defaults that a specific project can override.

Creating Skills

Two ways: manual or automatic.

Manual: Run skill-creator create and follow the guided workflow. It asks for a name, purpose, trigger patterns, and content, then writes the SKILL.md file for you.

Automatic: Just work. Skill Creator watches your sessions. When it sees you do the same thing three or more times, it suggests creating a skill. You review, approve, defer, or dismiss. Nothing happens without your say-so.

Agents: Composed Expertise

An agent is a bundle of skills with a specific role. If skills are individual pieces of knowledge, agents are specialists who know several things and can apply them together.

Agents emerge in two ways:

Automatic composition: When Skill Creator detects that certain skills consistently activate together — at least 5 co-activations over 7 or more days — it suggests combining them into an agent. This isn't a guess; it's based on observed patterns in your actual work.

Manual creation: You define an agent directly in .claude/agents/ with a Markdown file that specifies which skills to include, what model to use, and what tools are allowed.

Agents follow the official Claude Code agent format:

---
name: react-fullstack-agent
description: Combines react-hooks, react-components, and
  api-patterns for full-stack React development.
tools: Read, Write, Edit, Bash, Glob, Grep
model: inherit
skills:
  - react-hooks
  - react-components
  - api-patterns
---

You are a specialized agent combining expertise from the
listed skills. When invoked, apply the combined knowledge
to complete the task effectively.

Teams: Multi-Agent Coordination

Teams coordinate multiple agents working on the same project. This is where things get powerful — and where it starts to matter how agents communicate and divide work.

Skill Creator supports five topology patterns:

Teams are defined in chipset YAML configurations (covered next) and integrate directly with GSD's phase execution model. When GSD runs execute-phase, it can use team topologies to distribute plans across agents working in parallel waves.

The Chipset Architecture

Why It Exists

This is the deepest technical concept in Skill Creator, and it draws directly from the Commodore Amiga's 1985 hardware design. If you're not interested in the internal architecture, you can skip this section — everything above works without understanding it. But if you want to know why the system works as well as it does, this is the key insight.

In 1985, the Amiga shipped with custom chips — Agnus (memory/DMA), Denise (graphics), and Paula (audio/IO). No single chip was as powerful as competing general-purpose processors. But because each was precisely designed for its domain, and they communicated through a shared bus, the Amiga produced multimedia capabilities that machines with far more raw power couldn't match. A 7 MHz system outperformed 16 MHz competitors.

The insight: the right constraints, applied to the right components, composed through the right interfaces, produce capabilities that exceed the sum of their parts. This is architectural leverage.

Skill Creator's agent architecture applies this same principle to AI agents. Instead of one giant context window trying to do everything (which degrades), the work is distributed across specialized engines that each own a specific domain.

The Four Engines

Skill Creator defines four engine domains, each a specialized coprocessor:

Each engine gets three things:

• Budget channels — A percentage of the total token budget, with guaranteed minimums. Just like DMA channels in the Amiga gave each chip guaranteed access to memory bandwidth.
• Message ports — Named, typed, FIFO queues for communication between engines. Each port declares a direction (in, out, or bidirectional) and the message types it accepts.
• A 32-bit signal mask — Lightweight wake/sleep coordination. Bits 0–15 are system-reserved (kernel use), bits 16–31 are user-allocatable (engine-specific). This lets engines notify each other without expensive message passing.

The Kernel

The ExecKernel ties it all together. It's a tick-driven execution engine that runs one scheduling round per tick:

1. Run the scheduler (which engines are awake, which are sleeping)
2. Process pending messages on each engine's inbound port
3. Track budget consumption

The kernel manages lifecycle (idle → running → stopped), routes messages through MessagePort FIFO transport, and provides sleep/wake primitives for engines. It's deliberately thin — the kernel never does heavy work itself. It coordinates. The work happens in the engines.

This is exactly how the original Amiga's Exec kernel worked: a lightweight scheduler coordinating specialized coprocessors through shared memory and interrupt signals.

Copper Lists

In the Amiga, the "Copper" was a display coprocessor that could execute simple programs synchronized to the video beam. Copper lists were sequences of WAIT and MOVE instructions that told the hardware "when the display reaches line 100, change the background color."

Skill Creator borrows this concept. Copper lists are declarative workflow programs — sequences of WAIT, MOVE, and SKIP instructions synchronized to GSD lifecycle events instead of scanlines. For example:

• WAIT for GSD to enter the plan-phase event
• MOVE the relevant domain skills into the context engine's budget
• WAIT for execute-phase
• MOVE the test harness skill into context and activate the verification agent
• SKIP the debug skill if all tests pass

This means you can program exactly which skills and agents activate at each point in the GSD lifecycle, declaratively, without writing imperative code. The copper compiler turns these high-level lists into the kernel's scheduling instructions.

Copper lists also support a learning mode: the system can observe which skills actually activated at each lifecycle stage, compare against the copper list's predictions, and suggest refinements — closing the loop between declarative programs and real-world usage.

The Blitter

On the Amiga, the Blitter was a chip for fast memory-to-memory block operations — it handled bulk data movement so the CPU didn't have to. In Skill Creator, the Blitter handles script execution: promoting scripts from skill metadata, running them as child processes with timeouts, and signaling completion.

When a skill includes automation scripts (in its scripts/ directory), the Blitter manages their lifecycle. It's the engine that turns declarative skill definitions into running processes — the bridge between "this skill says to run lint" and actually executing the lint command.

Chipset YAML

Everything comes together in a single chipset.yaml file. This is the configuration that defines the entire system for a given domain. Here's a simplified example from the Electronics Educational Pack:

name: electronics
version: 0.1.0
description: "Electronics Educational Pack"

skills:
  - id: circuit-fundamentals
    name: Circuit Fundamentals
    triggers: [voltage, current, resistance, ohm]
    module: 01-the-circuit
    tier: 1

  - id: transistor-circuits
    name: Transistor Circuits
    triggers: [transistor, BJT, MOSFET, amplifier]
    module: 05-transistors
    tier: 2

  # ... 12 more skills ...

agents:
  - id: EL-1
    name: circuit-instructor
    role: "Foundation instructor"
    skills: [circuit-fundamentals, passive-components,
             signal-analysis]
    tier: 1

  - id: EL-4
    name: digital-instructor
    role: "Digital and mixed-signal instructor"
    skills: [logic-gate-design, sequential-logic,
             data-conversion, dsp-fundamentals]
    tier: 3

  # ... 3 more agents ...

topology:
  type: pipeline
  flow:
    - from: EL-1
      to: [EL-2, EL-3]
    - from: EL-2
      to: [EL-4]
    - from: EL-3
      to: [EL-4]
    - from: EL-4
      to: [EL-5]

One file defines all skills, all agents, their team topology, and how they flow into each other. The system boots deterministically from this file. You can version it, share it, fork it, or swap it for a completely different domain configuration.

Educational & Knowledge Packs

Knowledge packs extend the skill system beyond coding into structured education. They were introduced in v1.27 and are designed for teachers, curriculum designers, and anyone who wants to create or follow a structured learning experience.

There are currently 35 foundational knowledge packs organized into three tiers:

What's Inside a Pack

Each pack is a self-contained learning module with a consistent structure:

• Vision document — The pedagogical philosophy, parent guidance, and FAQ
• Modules YAML — 5 modules per pack with competencies and progression pathways
• Activities JSON — Concrete learning activities (hands-on experiments, discussions, projects)
• Assessment — Rubric-based evaluation emphasizing competency over memorization
• Resources — Curated external references
• Standards alignment — Mapped to Common Core, NGSS, IB MYP, UK National Curriculum, and others

Learning Pathways

Packs form a dependency graph with recommended (not required) prerequisites. Eight entry points let learners start from their interests:

MATH-101 → STAT-101 → DATA-101 → ECON-101
    ↓
PHYS-101 → ENGR-101 → TRADE-101
    ↓
ASTRO-101

READ-101 → COMM-101 → WRIT-101
    ↓
CRIT-101 → LOGIC-101 → PHILO-101

TECH-101 → CODE-101 → DATA-101

No prerequisites are hard blockers — all are recommended. This maximizes learner agency. A curious student can jump into astronomy without finishing physics first; they'll just get a note that physics background would help.

The Learning Loop

Knowledge packs integrate with the same observation infrastructure that drives skill creation. The system watches how a learner interacts with pack content, detects learning patterns (sequence patterns, timing patterns, engagement patterns), adapts pathways, scaffolds activities, and when it sees strong patterns, promotes them into skills. The same observe → detect → suggest → refine loop that makes coding workflows better also makes educational experiences better.

Domain Packs

Beyond the 35 foundational packs, there are deeper domain-specific packs like the Electronics Educational Pack (v1.29) with circuit simulators, logic simulators, 77 interactive labs, and 5 specialized computation engines. These are full educational environments with simulation capabilities, not just documents.

The Learning Loop

The learning loop is Skill Creator's core innovation. It's what makes the system get better the more you use it, and it works the same way whether you're coding or studying electronics.

Observe: Watches tool sequences, file patterns, corrections, and outcomes across sessions. Stores compact summaries (not full transcripts) in append-only JSONL files.

Detect: Identifies recurring workflows using n-gram extraction and DBSCAN clustering when patterns repeat 3+ times.

Suggest: Proposes skill creation from detected patterns. Always requires your explicit confirmation. You can accept, defer (ask again in 7 days), or dismiss (never ask again).

Apply: Loads relevant skills automatically based on context, within the 2–5% token budget. The 6-stage pipeline handles scoring, conflict resolution, and budget management.

Learn: Refines skills from your corrections. This has strict safety guardrails to prevent runaway changes:

Compose: When skills consistently co-activate (5+ times over 7+ days), proposes agents. When agent clusters stabilize, proposes teams. The composition is always data-driven and always requires your approval.

The Mental Model

Here's the simplest way to think about the entire system:

Claude Code is the engine. It's incredibly powerful, but it has no memory, no plan, and no sense of the bigger picture.

GSD is the project manager. It gives the engine a plan, tracks progress, maintains state, and makes sure each piece of work happens in a clean environment with clear success criteria. GSD prevents degradation within a project.

Skill Creator is the institutional memory. It watches how you work, captures what matters, and builds it into reusable knowledge that persists across projects, across sessions, and across time. Skill Creator prevents forgetting between projects.

Together, they create something that neither can do alone: an AI development environment that stays sharp during long builds, remembers your preferences across months of work, and gets measurably better the more you use it.

Start where you are. If you've never built anything, install GSD and run /gsd:new-project. If you're experienced and tired of re-explaining yourself, install Skill Creator and let it start watching. If you're an architect ready for multi-agent orchestration, dive into chipset YAML and team topologies.

The system meets you where you are and grows with you.