create-gsd-extension
Create, debug, and iterate on GSD extensions (TypeScript modules adding tools, commands, event hooks, custom UI, and providers). 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/build extension", "add a tool", "register command", "hook into gsd", "gsd plugin".
- License 许可
- MIT
- 所属仓库
- open-gsd/gsd-pi
- 最近更新
- 2026-11-15
- Stars
- ★ 1.4k
- Forks
- 118
01 前言 Front Matter
- name
- create-gsd-extension
- description
- Create, debug, and iterate on GSD extensions (TypeScript modules adding tools, commands, event hooks, custom UI, and providers). 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/build extension", "add a tool", "register command", "hook into gsd", "gsd plugin".
02 资源文件 22
- 参考文档references/compaction-session-control.md2.3 KB
- 参考文档references/custom-commands.md4.0 KB
- 参考文档references/custom-rendering.md3.2 KB
- 参考文档references/custom-tools.md5.4 KB
- 参考文档references/custom-ui.md18.6 KB
- 参考文档references/events-reference.md4.2 KB
- 参考文档references/extension-lifecycle.md2.6 KB
- 参考文档references/extensionapi-reference.md2.5 KB
- 参考文档references/extensioncontext-reference.md2.2 KB
- 参考文档references/key-rules-gotchas.md2.1 KB
- 参考文档references/mode-behavior.md1.1 KB
- 参考文档references/model-provider-management.md2.6 KB
- 参考文档references/packaging-distribution.md1.2 KB
- 参考文档references/remote-execution-overrides.md2.6 KB
- 参考文档references/state-management.md2.3 KB
- 参考文档references/system-prompt-modification.md1.5 KB
- 脚本templates/extension-skeleton.ts1.2 KB
- 脚本templates/stateful-tool-skeleton.ts4.7 KB
- 脚本templates/templates.test.ts3.8 KB
- 参考文档workflows/add-capability.md1.7 KB
- 参考文档workflows/create-extension.md5.4 KB
- 参考文档workflows/debug-extension.md2.4 KB
03 SKILL.md 正文
<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>
<routing> Based on user intent, route to the appropriate workflow:
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. </routing>
<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-pi 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>
04 同仓库更多 Skills
write-milestone-brief
Synthesize the current conversation into a milestone brief (PRD). Saves it as the milestone CONTEXT (`gsd_summary_save`) by default, or files a GitHub issue only with explicit user confirmation. Use when asked to "turn this into a PRD", "draft a milestone brief", "capture this context", "write it up", or when enough has been discussed to commit the plan to paper. Does not interview — it synthesizes what is already known.
write-docs
Collaborative authoring workflow for proposals, technical specs, decision docs, READMEs, ADRs, and long-form prose that must work for fresh readers. Three stages: gather context, iterate on structure, reader-test for a stranger. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a doc must be understandable without this session's context.
web-quality-audit
Comprehensive web quality audit covering performance, accessibility, SEO, and best practices. Use when asked to "audit my site", "review web quality", "run lighthouse audit", "check page quality", or "optimize my website".
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
verify-before-complete
Block completion claims until verification evidence has been produced in the current message. Use before marking a task/slice/milestone complete, before creating a commit or PR, before saying "it works" or "tests pass", and any time you are about to claim work is done. The rule is: evidence before claims, always — running the verification must happen now, not "earlier in the session". Fresh output or no claim.
userinterface-wiki
UI/UX best practices for web interfaces. Use when reviewing animations, CSS, audio, typography, UX patterns, prefetching, or icon implementations. Covers 11 categories from animation principles to typography. Outputs file:line findings.