create-gsd-extension
GitHub用于创建、调试和迭代 GSD 扩展（TypeScript 模块），支持添加工具、命令、事件钩子及自定义 UI。适用于构建插件或修改 GSD 行为。
Trigger Scenarios
Install
npx skills add gsd-build/gsd-2 --skill create-gsd-extension -g -y
SKILL.md
Frontmatter
{
"name": "create-gsd-extension",
"description": "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\"."
}
<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>
Version History
- 33c00aa Current 2026-07-25 10:22
