Create Gsd Extension
Agent Buildingcreate-gsd-extensionCreate Gsd Extension is an Agent Skill for agent building published in the gsd-build/gsd-2 repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Create, debug, and iterate on GSD extensions (TypeScript modules that add tools, commands, event hooks, custom UI, and providers to GSD). Use when asked to build an extension, add a tool the LLM can call, register a slash command, hook into GSD events, create custom TUI components, or modify GSD behavior. Triggers on "create extension", "build extension", "add a tool", "register command", "hook into gsd", "custom tool", "gsd plugin", "gsd extension".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/gsd-build/gsd-2/blob/HEAD/src/resources/skills/create-gsd-extension/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/create-gsd-extension, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
<essential_principles>
Extensions are TypeScript modules that hook into GSD's runtime (built on pi). They export a default function receiving ExtensionAPI and use it to subscribe to events, register tools/commands/shortcuts, and interact with the session.
GSD extension paths (community/user-installed extensions):
- Global:
~/.pi/agent/extensions/*.tsor~/.pi/agent/extensions/*/index.ts - Project-local:
.gsd/extensions/*.tsor.gsd/extensions/*/index.ts
Note: ~/.gsd/agent/extensions/ is reserved for bundled extensions synced from the gsd-pi package. Community extensions placed there are silently ignored by the loader.
The three primitives:
- Events — Listen and react (
pi.on("event", handler)). Can block tool calls, modify messages, inject context. - Tools — Give the LLM new abilities (
pi.registerTool()). LLM calls them autonomously. - Commands — Give users slash commands (
pi.registerCommand()). Users type/mycommand.
Non-negotiable rules:
- Use
StringEnumfrom@gsd/pi-aifor string enum params (NOTType.Union/Type.Literal— breaks Google's API) - Truncate tool output to 50KB / 2000 lines max (use
truncateHead/truncateTailfrom@gsd/pi-coding-agent) - Store stateful tool state in
detailsfor branching support - Check
signal?.abortedin long-running tool executions - Use
pi.exec()notchild_processfor shell commands - Check
ctx.hasUIbefore dialog methods (non-interactive modes exist) - Session control methods (
waitForIdle,newSession,fork,navigateTree,reload) are ONLY available in command handlers — they deadlock in event handlers - Lines from
render()must not exceedwidth— usetruncateToWidth() - Use theme from callback params, never import directly
- Strip leading
@from path params in custom tools (some models add it)
Available imports:
| Package | Purpose |
|---|---|
@gsd/pi-coding-agent | ExtensionAPI, ExtensionContext, Theme, event types, tool utilities, DynamicBorder, BorderedLoader, CustomEditor, highlightCode |
@sinclair/typebox | Type.Object, Type.String, Type.Number, Type.Optional, Type.Boolean, Type.Array |
@gsd/pi-ai | StringEnum (required for string enums), Type re-export |
@gsd/pi-tui | Text, Box, Container, Spacer, Markdown, SelectList, Input, matchesKey, Key, truncateToWidth, visibleWidth |
| Node.js built-ins | node:fs, node:path, node:child_process, etc. |
</essential_principles>
Building a new extension:
- "Create an extension", "build a tool", "I want to add a command" →
workflows/create-extension.md
Adding capabilities to an existing extension:
- "Add a tool to my extension", "add event hook", "add custom rendering" →
workflows/add-capability.md
Debugging an extension:
- "My extension doesn't work", "tool not showing up", "event not firing" →
workflows/debug-extension.md
If user intent is clear from context, skip the question and go directly to the workflow.
<reference_index>
All domain knowledge in references/:
Core architecture: extension-lifecycle.md, events-reference.md
API surface: extensionapi-reference.md, extensioncontext-reference.md
Capabilities: custom-tools.md, custom-commands.md, custom-ui.md, custom-rendering.md
Patterns: state-management.md, system-prompt-modification.md, compaction-session-control.md
Infrastructure: model-provider-management.md, remote-execution-overrides.md, packaging-distribution.md, mode-behavior.md
Spec: docs/extension-sdk/manifest-spec.md — manifest format, tiers, validation
Testing: docs/extension-sdk/testing.md — mock patterns, test conventions
SDK: docs/extension-sdk/ — the authoritative GSD-2 extension guide
Gotchas: key-rules-gotchas.md
</reference_index>
<workflows_index>
| Workflow | Purpose |
|---|---|
| create-extension.md | Build a new extension from scratch |
| add-capability.md | Add tools, commands, hooks, UI to an existing extension |
| debug-extension.md | Diagnose and fix extension issues |
| </workflows_index> |
<success_criteria> Extension is complete when:
extension-manifest.jsonexists with accurateprovideslisting all registered tools/commands/hooks/shortcuts- TypeScript compiles without errors (jiti handles this at runtime)
- Extension loads on GSD startup or
/reloadwithout errors - Tools appear in the LLM's system prompt and are callable
- Commands respond to
/commandinput - Event hooks fire at the expected lifecycle points
- Custom UI renders correctly within terminal width
- State persists correctly across session restarts (if stateful)
- Output is truncated to safe limits (if tools produce variable output) </success_criteria>