| Guide ID | A-5 |
|---|---|
| Audience | Contributors, Advanced developers |
| Prerequisites | A-1: Chipset Architecture, A-2: 6-Stage Pipeline |
| Time | 25 minutes |
| Difficulty | Expert |
Extending the Pipeline
The Amiga’s chipset was not a closed system. The Zorro expansion bus allowed third-party hardware to extend the machine’s capabilities — graphics cards, memory boards, networking interfaces — without modifying the core chipset. gsd-skill-creator follows the same principle: the core pipeline (Score, Resolve, ModelFilter, CacheOrder, Budget, Load) is designed to be extended at defined integration points without modifying the pipeline stages themselves.
This page documents every extension point in the system, from the stable fields you can use today to the future extension mechanisms planned for upcoming versions. Each extension point is annotated with its stability level: STABLE fields have a fixed API and will not change; EXPERIMENTAL fields may evolve.
Extension Points Overview
The system is designed to be extended at five levels, ordered from simplest to most complex:
1. Custom frontmatter fields — Add metadata to skills that influences pipeline behavior (scoring, filtering, budgeting). This is the most common extension and requires no code changes.
2. Skill inheritance — Create parent-child relationships between skills, where child skills inherit and override parent content. This enables skill families without content duplication.
3. Threshold tuning — Customize activation thresholds per-skill or per-command to control when skills load. This refines the Score stage’s behavior without modifying it.
4. Embedding configuration — Select embedding models and manage embedding caches for semantic matching in the Score stage and the Orchestrator’s semantic fallback.
5. Structural extensions (v1.7+) — Workflows, roles, and bundles that compose skills into higher-order constructs. These are the expansion cards of the system.
Custom Frontmatter Fields
gsd-skill-creator extends the official Claude Code skill format with additional frontmatter fields stored under metadata.extensions.gsd-skill-creator. This namespaced location keeps extension fields separate from official Claude Code fields, allows multiple tools to store extensions without conflicts, and follows the documented extension pattern.
The extension fields are:
| Field | Type | Stability | Purpose |
|---|---|---|---|
triggers | SkillTrigger | STABLE | Auto-activation conditions (intents, files, contexts) |
triggers.intents | string[] | STABLE | Intent keywords that activate the skill |
triggers.files | string[] | STABLE | File glob patterns (e.g., "*.tsx", "src/**/*.ts") |
triggers.contexts | string[] | STABLE | Context keywords (e.g., "in GSD planning phase") |
triggers.threshold | number | STABLE | Minimum relevance score for activation (0–1, default 0.5) |
enabled | boolean | STABLE | Whether skill is active (default true) |
version | number | STABLE | Auto-incremented on updates |
extends | string | STABLE | Parent skill name for inheritance |
createdAt | string | STABLE | ISO 8601 creation timestamp |
updatedAt | string | STABLE | ISO 8601 last update timestamp |
learning | SkillLearning | EXPERIMENTAL | Feedback tracking (application count, corrections, scores) |
forceOverrideReservedName | object | EXPERIMENTAL | Tracks when reserved name protection was bypassed |
forceOverrideBudget | object | EXPERIMENTAL | Tracks when budget limit was bypassed |
These fields coexist cleanly with the official Claude Code format. A skill with extension fields works in standard Claude Code even without gsd-skill-creator installed — the extension fields are simply ignored. When gsd-skill-creator is present, it reads the extensions via the getExtension(metadata) accessor, which handles both the current namespaced location and the legacy root-level location transparently.
Source: docs/EXTENSIONS.md, src/types/skill.ts (type definitions with deprecation annotations)
Skill Inheritance
The extends field creates parent-child relationships between skills. A child skill inherits its parent’s content and can override specific sections. This enables skill families: a base code-helper skill might provide general coding guidance, while typescript-helper extends it with TypeScript-specific patterns, and react-helper extends typescript-helper with React component patterns.
Inheritance is resolved during the Resolve stage of the pipeline. The composition module (src/composition/) builds a dependency graph from all extends declarations and computes the effective skill content by walking the inheritance chain. For each section (heading-delimited block in the Markdown body), the child’s version overrides the parent’s. Sections present in the parent but absent in the child are inherited unchanged. Sections present in the child but absent in the parent are additions.
Circular inheritance (A extends B extends A) is detected during dependency graph construction and raises a validation error. Deep inheritance chains (more than 3 levels) are technically supported but raise a warning, because deep inheritance makes skill behavior harder to predict.
Design rationale: Skill inheritance was considered against two alternatives: skill merging (combining content from multiple skills into one) and skill composition (referencing other skills by name). Merging was rejected because it produces unpredictable results when sections conflict. Composition was rejected because it does not reduce the total content volume — referenced skills still need to be loaded separately. Inheritance provides a clear override model (child wins) and reduces content duplication (shared sections are defined once in the parent).
Custom Threshold Tuning
The default activation threshold (0.5) works well for most skills, but some skills benefit from custom tuning. A highly specialized skill (e.g., one that should only load when working with a specific framework) might use a threshold of 0.7 or 0.8 to avoid false activations. A broadly useful skill (e.g., commit conventions) might use a threshold of 0.3 to load in more contexts.
Thresholds are set per-skill in the triggers.threshold field. The Score stage converts this threshold (0–1 scale) to the internal scoring scale (0–100) and eliminates skills that score below their individual threshold. This means different skills in the same session can have different activation sensitivity.
For systematic threshold tuning across multiple skills, use the calibration system (src/calibration/). The skill-creator test command runs activation simulations against historical session data, showing which skills would have activated (and which would not) at different threshold levels. This allows data-driven threshold adjustment rather than guesswork.
Source: src/calibration/ (threshold tuning), src/simulation/ (activation simulation), src/testing/ (test infrastructure)
Embedding Configuration
The Score stage and the Orchestrator’s semantic fallback both use embeddings for semantic similarity matching. gsd-skill-creator supports local embedding models and falls back to heuristic text matching when embeddings are unavailable (e.g., on machines without GPU support or without a configured embedding server).
Use skill-creator reload-embeddings to regenerate embedding caches when the embedding model changes, when GPU availability changes, or when significant skill content has been updated. The embedding cache stores precomputed vectors for all skill descriptions and trigger intents, avoiding redundant computation during pipeline runs.
The heuristic fallback uses keyword overlap, TF-IDF weighting, and string similarity metrics. It is deterministic and fast but less accurate than embedding-based matching for semantically similar but lexically different inputs. The fallback is transparent to the rest of the pipeline — the Score stage produces the same output format regardless of which similarity method is used.
Source: src/embeddings/ (local embedding infrastructure)
Workflow Definitions (v1.7)
Workflow definitions (.claude/workflows/<name>.workflow.yaml) chain multiple skills into multi-step sequences with defined inputs, outputs, and transition conditions. A workflow might define: “when a test file is modified, first run the linting skill, then the testing skill, then the commit skill.” Each step specifies which skill to activate, what context to pass, and what conditions must be met to proceed to the next step.
Workflows support event-driven inter-skill communication. Completing one step can emit an event that triggers the next step, enabling asynchronous workflow execution. The event bus (src/events/) manages event routing, and execution state is tracked in .planning/patterns/workflow-runs.jsonl.
Role Definitions (v1.7)
Role definitions (.claude/roles/<name>.role.yaml) apply behavioral constraints to skills. A “reviewer” role might allow read operations but prohibit write operations, ensuring that skills activated during code review cannot accidentally modify files. A “deployer” role might restrict which commands can be executed, limiting skills to deployment-related operations.
Roles interact with the GSD Orchestrator: when a role is active, the Orchestrator respects its constraints when suggesting commands. A reviewer role prevents the Orchestrator from routing to /gsd:execute-phase.
Bundle Definitions (v1.7)
Bundle definitions (.claude/bundles/<name>.bundle.yaml) group skills into project-phase sets. A “frontend” bundle might include TypeScript patterns, React component skills, CSS-in-JS conventions, and accessibility guidelines. Activating the bundle loads all its skills as a group, ensuring consistent context for a specific type of work.
Bundles differ from agents in scope and intent. An agent is a composite intelligence that combines skills into a single entity with a unified description. A bundle is a convenience grouping that loads skills individually but ensures they are all present. Agents are spawned as subagents; bundles modify the current session’s skill set.
MCP Distribution (v1.9)
The Model Context Protocol (MCP) extension point enables distributing skills via MCP servers. Rather than requiring skills to be installed locally, a skill server can provide skills over the network, allowing organizations to maintain centralized skill repositories that multiple projects consume. See A-6: MCP Integration for the full architecture of MCP-based skill distribution.
Migration Paths
The extension system includes migration support for deprecated patterns:
Root-level extension fields (v1.0.0+). Extension fields originally lived at the root level of the frontmatter. They now live under metadata.extensions.gsd-skill-creator. Migration is automatic — skills are migrated on save. The getExtension() accessor handles both locations transparently.
Flat-file to directory format (v1.0.0+). Skills originally lived as single .md files. They now live in directories with SKILL.md, optional reference.md, and optional scripts/. Run skill-creator migrate to convert.
Agent tools array format (v1.0.0+). Agent tools fields originally used YAML arrays. They now use comma-separated strings. Run skill-creator migrate-agent to convert.
Source: docs/EXTENSIONS.md (complete migration guide with before/after examples)
What’s Next
- A-1: Chipset Architecture — The coprocessor model that extensions build upon
- A-2: 6-Stage Pipeline — The pipeline stages that extensions customize
- A-6: MCP Integration — Network-based skill distribution
- T-3: Skill Format — Practical guide to skill frontmatter