Extensions - GSD Skill Creator

Documentation > Reference > Extensions

gsd-skill-creator Extension Reference

This document describes extension fields added by gsd-skill-creator beyond the official Claude Code format. These extensions enable trigger-based activation, learning/feedback tracking, and skill inheritance.

Overview

Extensions are stored under metadata.extensions.gsd-skill-creator in skill files:

---
name: my-skill
description: My skill description
metadata:
  extensions:
    gsd-skill-creator:
      triggers:
        intents: ["typescript", "react"]
      version: 1
      createdAt: "2026-01-31T12:00:00Z"
---

This namespaced location keeps official Claude Code fields separate from tool-specific data, allows multiple tools to store extensions without conflicts, and follows Claude Code’s documented extension pattern.

Extension Fields

Field	Type	Default	Stability	Purpose
`triggers`	`SkillTrigger`	`undefined`	STABLE	Auto-activation conditions
`learning`	`SkillLearning`	`undefined`	EXPERIMENTAL	Feedback and refinement tracking
`enabled`	`boolean`	`true`	STABLE	Whether skill is active
`version`	`number`	`undefined`	STABLE	Version number, incremented on updates
`extends`	`string`	`undefined`	STABLE	Parent skill name to inherit from
`createdAt`	`string`	`undefined`	STABLE	ISO 8601 timestamp of creation
`updatedAt`	`string`	`undefined`	STABLE	ISO 8601 timestamp of last update
`forceOverrideReservedName`	`object`	`undefined`	EXPERIMENTAL	Tracking for reserved name bypass
`forceOverrideBudget`	`object`	`undefined`	EXPERIMENTAL	Tracking for budget limit bypass

Triggers

The triggers field enables automatic skill activation based on context matching.

Trigger Fields

Field	Type	Default	Purpose
`intents`	`string[]`	`[]`	Intent patterns for auto-activation (keywords, regex)
`files`	`string[]`	`[]`	File glob patterns (e.g., `".tsx"`, `"src//.ts"`)
`contexts`	`string[]`	`[]`	Context keywords (e.g., `"in GSD planning phase"`)
`threshold`	`number`	`0.5`	Minimum relevance score (0-1) for activation

Trigger Example

metadata:
  extensions:
    gsd-skill-creator:
      triggers:
        intents:
          - typescript
          - react component
          - frontend
        files:
          - "*.tsx"
          - "*.ts"
          - "src/components/**"
        contexts:
          - building UI
          - working on frontend
        threshold: 0.6

Learning

The learning field tracks skill usage and refinement for adaptive improvement.

Learning Fields

Field	Type	Default	Purpose
`applicationCount`	`number`	`0`	Times the skill has been applied
`feedbackScores`	`number[]`	`[]`	User feedback scores (1-5 scale)
`corrections`	`SkillCorrection[]`	`[]`	Captured corrections/overrides
`lastRefined`	`string`	`undefined`	ISO 8601 timestamp of last refinement

SkillCorrection Fields

Field	Type	Required	Purpose
`timestamp`	`string`	yes	ISO 8601 timestamp of correction
`original`	`string`	yes	Original output that was corrected
`corrected`	`string`	yes	User’s corrected version
`context`	`string`	no	Additional context about the correction

Force Override Fields

These fields track when users bypass safety protections.

forceOverrideReservedName

Recorded when user creates a skill with a reserved name.

Field	Type	Purpose
`reservedName`	`string`	The reserved name that was used
`category`	`string`	Category (e.g., built-in-commands, agent-types)
`reason`	`string`	Why the name was reserved
`overrideDate`	`string`	ISO 8601 timestamp of override

forceOverrideBudget

Recorded when user creates/updates a skill that exceeds character budget.

Field	Type	Purpose
`charCount`	`number`	Character count at time of override
`budgetLimit`	`number`	Budget limit that was exceeded
`usagePercent`	`number`	Usage percentage at time of override
`overrideDate`	`string`	ISO 8601 timestamp of override

Stability Indicators

Indicator	Meaning
STABLE	API will not change. Safe to depend on in tooling and scripts.
EXPERIMENTAL	May change in future versions. Use with awareness that migration may be needed.

Stable Fields

triggers, enabled, version, extends, createdAt, updatedAt

Experimental Fields

learning, forceOverrideReservedName, forceOverrideBudget

Migration Guide

Root-Level Extension Fields (v1.0.0+)

In v1.0.0, extension fields moved from root level to metadata.extensions.gsd-skill-creator. Migration is automatic on save.

// Programmatic access works for both old and new format
import { getExtension } from 'gsd-skill-creator';
const ext = getExtension(skill.metadata);
console.log(ext.triggers); // Always finds triggers

Flat-File to Directory Format (v1.0.0+)

# Migrate all skills
skill-creator migrate

# Migrate specific skill
skill-creator migrate my-skill

Agent Tools Array Format (v1.0.0+)

Agent tools field changed from YAML array to comma-separated string.

skill-creator migrate-agent

Troubleshooting

Error	Cause	Solution
Skill already in directory format	Running migrate on current format	No action needed
Invalid skill name	Name has uppercase or special chars	Use `skill-creator validate` to see suggested fix
Skill not found	Skill doesn’t exist at specified scope	Check scope with `skill-creator list --scope=all`
Reserved name conflict	Skill name conflicts with built-in	Use `--force` flag or rename skill
Budget exceeded	Skill content too large	Reduce content or use `--force` flag

Known Issues

User-Level Agent Discovery (GitHub #11205)

Status: Known bug in Claude Code

Agents stored in ~/.claude/agents/ may not be automatically discovered by Claude Code at session startup. Project-level agents in .claude/agents/ work correctly.

Workarounds:

Use project-level agents (recommended)
Use the /agents UI command within Claude Code
Pass agents via CLI flag: claude --agents=path/to/agent.md