AGENT SKILL

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

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/*.ts or ~/.pi/agent/extensions/*/index.ts
  • Project-local: .gsd/extensions/*.ts or .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:

  1. Events — Listen and react (pi.on("event", handler)). Can block tool calls, modify messages, inject context.
  2. Tools — Give the LLM new abilities (pi.registerTool()). LLM calls them autonomously.
  3. Commands — Give users slash commands (pi.registerCommand()). Users type /mycommand.

Non-negotiable rules:

  • Use StringEnum from @gsd/pi-ai for string enum params (NOT Type.Union/Type.Literal — breaks Google's API)
  • Truncate tool output to 50KB / 2000 lines max (use truncateHead/truncateTail from @gsd/pi-coding-agent)
  • Store stateful tool state in details for branching support
  • Check signal?.aborted in long-running tool executions
  • Use pi.exec() not child_process for shell commands
  • Check ctx.hasUI before 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 exceed width — use truncateToWidth()
  • 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.json exists with accurate provides listing all registered tools/commands/hooks/shortcuts
  • TypeScript compiles without errors (jiti handles this at runtime)
  • Extension loads on GSD startup or /reload without errors
  • Tools appear in the LLM's system prompt and are callable
  • Commands respond to /command input
  • 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

open-gsd
open-gsd/gsd-pi

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.

★ 1.4k
open-gsd
open-gsd/gsd-pi

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.

★ 1.4k
open-gsd
open-gsd/gsd-pi

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".

★ 1.4k
open-gsd
open-gsd/gsd-pi

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".

★ 1.4k
open-gsd
open-gsd/gsd-pi

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.

★ 1.4k
open-gsd
open-gsd/gsd-pi

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.

★ 1.4k