Documentation > Developer Guide > File Structure
User Project Layout
your-project/
├── .claude/
│ ├── skills/ # Skill storage
│ │ └── <skill-name>/
│ │ ├── SKILL.md # Main skill file (frontmatter + content)
│ │ ├── reference.md # Optional reference material
│ │ └── scripts/ # Optional automation scripts
│ ├── agents/ # Generated/custom agents
│ │ └── <agent-name>.md # Composite agent file
│ ├── teams/ # Agent team configurations
│ │ └── <team-name>.json # Team config (members, topology)
│ ├── workflows/ # Skill workflow definitions (v1.7)
│ │ └── <name>.workflow.yaml # Multi-step skill chains
│ ├── roles/ # Skill role definitions (v1.7)
│ │ └── <name>.role.yaml # Behavioral constraints
│ ├── bundles/ # Work bundle definitions (v1.7)
│ │ └── <name>.bundle.yaml # Project-phase skill sets
│ └── settings.json # Claude Code settings (hooks, etc.)
│
├── .planning/
│ ├── patterns/ # Observation data
│ │ ├── sessions.jsonl # Session observations (append-only)
│ │ ├── suggestions.json # Skill suggestion state
│ │ ├── feedback.jsonl # User corrections/feedback
│ │ ├── agent-suggestions.json # Agent suggestion state
│ │ ├── workflow-runs.jsonl # Workflow execution state (v1.7)
│ │ ├── events.jsonl # Inter-skill events (v1.7)
│ │ └── snapshots.jsonl # Session snapshots (v1.7)
│ ├── hooks/ # Work state persistence (v1.7)
│ │ └── current-work.yaml # Active task/skills/checkpoint
│ ├── PROJECT.md # Project context
│ ├── REQUIREMENTS.md # Requirements specification
│ ├── ROADMAP.md # Development roadmap
│ └── STATE.md # Session memory
│
└── node_modules/
└── dynamic-skill-creator/ # If installed as dependencySource Code Layout
src/ # TypeScript library
├── storage/ # Skill storage (SkillStore, PatternStore, SkillIndex)
├── types/ # TypeScript type definitions
├── workflows/ # CLI workflows (create, list, search)
├── application/ # Skill application + pipeline (v1.8)
│ └── stages/ # Pipeline stages (budget, cache-order, model-filter)
├── observation/ # Session observation
├── detection/ # Pattern detection
├── learning/ # Feedback learning
├── composition/ # Skill extension (dependency graph, resolver)
├── agents/ # Agent composition
├── embeddings/ # Local embedding infrastructure (v1.1)
├── conflicts/ # Conflict detection (v1.1)
├── activation/ # Activation scoring (v1.1)
├── testing/ # Test infrastructure (v1.2)
├── simulation/ # Activation simulation (v1.2)
├── calibration/ # Threshold tuning (v1.2)
├── teams/ # Agent team management (v1.4)
├── discovery/ # Pattern discovery from session logs (v1.5)
├── orchestrator/ # GSD Master Orchestration Agent (v1.7)
│ ├── discovery/ # Filesystem discovery
│ ├── state/ # Project state reading
│ ├── intent/ # Intent classification
│ ├── lifecycle/ # Lifecycle coordination
│ ├── verbosity/ # Output control
│ ├── gates/ # HITL approval gates
│ └── extension/ # gsd-skill-creator detection
├── work-state/ # Persistent work state (v1.7)
├── session-continuity/ # Session snapshots (v1.7)
├── ephemeral-observations/ # Tiered observations (v1.7)
├── workflows/ # Skill workflows (v1.7)
├── roles/ # Skill roles (v1.7)
├── bundles/ # Work bundles (v1.7)
├── events/ # Inter-skill communication (v1.7)
├── capabilities/ # Capability-aware planning (v1.8)
├── validation/ # Spec alignment & validation (v1.9+)
├── safety/ # Security & integrity (v1.10)
├── disclosure/ # Progressive disclosure (v1.9)
├── portability/ # Cross-platform export (v1.9)
├── evaluator/ # Evaluator-optimizer (v1.9)
├── mcp/ # MCP distribution (v1.9)
├── retrieval/ # Agentic RAG (v1.9)
├── hooks/ # Hook safety (v1.10)
├── integration/ # GSD integration layer (v1.11)
│ └── monitoring/ # Passive monitoring
├── dashboard/ # Planning docs dashboard (v1.12+)
│ ├── parser.ts # Markdown-to-HTML parser
│ ├── renderer.ts # HTML page renderer
│ ├── generator.ts # Multi-page generator pipeline
│ ├── collectors/ # Data collectors
│ ├── metrics/ # Live metrics engine
│ ├── design-system/ # CSS tokens, entity shapes, gantry strip
│ └── console/ # Console page, question cards, settings
├── identifiers/ # Domain-prefixed identifiers (v1.18)
├── terminal/ # Terminal launcher, health, session (v1.15)
├── launcher/ # Dashboard + terminal dev launcher (v1.15)
├── console/ # Filesystem message bus (v1.16)
├── amiga/ # AMIGA mission infrastructure (v1.23)
│ ├── mc1/ # MC-1 Control Surface
│ ├── me1/ # ME-1 Mission Environment
│ ├── ce1/ # CE-1 Commons Engine
│ ├── gl1/ # GL-1 Governance Layer
│ ├── icd/ # 4 typed Inter-Component Definitions
│ └── integration/ # Full-stack controller
├── agc/ # Apollo AGC Block II simulator (v1.23)
│ ├── cpu/ # 38-instruction CPU
│ ├── memory/ # Bank-switched memory
│ ├── interrupts/ # 10-vector interrupt system
│ ├── timing/ # 2.048 MHz timing model
│ ├── executive/ # Priority-based scheduler
│ ├── waitlist/ # Timer-driven task queue
│ ├── bailout/ # Restart protection
│ ├── dsky/ # Display model, keyboard
│ ├── monitor/ # Executive Monitor
│ ├── tools/ # yaYUL assembler, debugger
│ └── curriculum/ # 11 chapters, 8 exercises
├── cli/ # CLI command modules
├── cli.ts # CLI entry point
└── index.ts # Module exports
src-tauri/ # Rust backend (v1.21)
├── src/
│ ├── main.rs # Tauri application entry point
│ ├── pty/ # Native PTY management
│ ├── watcher/ # File system watcher
│ ├── tmux/ # tmux session binding
│ ├── claude/ # Claude Code session management
│ └── ipc/ # Tauri IPC commands and events
├── Cargo.toml
└── tauri.conf.json
desktop/ # Vite webview frontend (v1.21)
├── src/
│ ├── engine/ # WebGL2 CRT shader engine
│ ├── terminal/ # xterm.js terminal emulator
│ ├── tmux/ # tmux session UI
│ ├── claude/ # Claude session UI
│ ├── ipc/ # Tauri IPC client wrappers
│ ├── wm/ # Window manager
│ ├── shell/ # Desktop shell
│ ├── dashboard/ # Dashboard rendering
│ ├── calibration/ # Three-screen calibration wizard
│ └── boot/ # Amiga chipset boot sequence
├── index.html
├── vite.config.ts
└── package.json
infra/ # Bash infrastructure scripts (v1.22)
├── scripts/ # Core infrastructure automation
│ ├── pxe/ # PXE boot server setup
│ ├── vm/ # VM provisioning
│ ├── minecraft/ # Fabric server deployment
│ ├── amiga/ # FS-UAE emulation
│ ├── platform/ # Hardware discovery
│ ├── backup/ # RCON-quiesced backups
│ └── monitoring/ # Prometheus metrics
├── skills/ # 20 formalized SKILL.md definitions
├── agents/ # 10 agent definitions
├── teams/ # 5 team configurations
├── packs/ # Educational content packs
├── templates/ # Configuration templates
├── runbooks/ # 4 operational runbooks
└── inventory/ # Hardware capability profiles
.chipset/ # Chipset configuration (v1.22)
├── chipset.yaml # Unified chipset definition
└── agc-educational.yaml # AGC educational chipset configSkill Type System Architecture
The type system in src/types/skill.ts defines the core data model for skills, including Claude Code compatibility fields, extension mechanisms for gsd-skill-creator metadata, and validation logic that enforces the official naming specification.
SkillMetadata Interface
The primary interface bridges Claude Code’s official skill fields with gsd-skill-creator’s extension data. Root-level Claude Code fields (name, description, allowed-tools, model, context) are required for compatibility, while extension data lives under metadata.extensions['gsd-skill-creator']. Legacy fields at root are preserved for backward compatibility but deprecated.
/**
* Claude Code skill metadata interface.
*
* Contains both official Claude Code fields at root level and a `metadata` container
* for extension fields. Legacy extension fields at root are preserved for backward
* compatibility but deprecated - use getExtension() to access extension data.
*/
export interface SkillMetadata {
// Required by Claude Code
name: string; // max 64 chars, lowercase + hyphens only
description: string; // max 1024 chars, used for auto-triggering
// Claude Code optional fields
'disable-model-invocation'?: boolean; // Prevent Claude from using
'user-invocable'?: boolean; // Allow /skill:name invocation
'allowed-tools'?: string[] | string; // Restrict available tools
'argument-hint'?: string; // Hint for user invocation arguments
model?: string; // Model override for skill execution
context?: 'fork'; // Fork context for isolated execution
agent?: string; // Agent reference for skill
hooks?: Record<string, unknown>; // Lifecycle hooks configuration
license?: string; // SPDX license identifier or free text
compatibility?: string; // Compatibility notes (max 500 chars)
// Official metadata container for extensions
metadata?: {
extensions?: {
'gsd-skill-creator'?: GsdSkillCreatorExtension;
/** Preserve unknown extensions from other tools */
[key: string]: unknown;
};
};
}Trigger and Learning Subsystem
Skills support auto-activation through intent patterns, file globs, and context matchers. The learning subsystem tracks application count, feedback scores, and user corrections — the raw data that drives skill refinement.
// Trigger conditions for auto-activation
export interface SkillTrigger {
// Match user intent patterns (regex or keywords)
intents?: string[];
// Match file patterns being worked on (glob)
files?: string[];
// Match context patterns (e.g., "in GSD planning phase")
contexts?: string[];
// Minimum confidence score to activate (0-1)
threshold?: number;
}
// Learning metadata for skill refinement
export interface SkillLearning {
// How many times skill has been applied
applicationCount?: number;
// User feedback scores (1-5)
feedbackScores?: number[];
// Corrections/overrides captured
corrections?: SkillCorrection[];
// Last refinement timestamp
lastRefined?: string;
}
export interface SkillCorrection {
timestamp: string;
original: string;
corrected: string;
context?: string;
}Name Validation
Skill names follow the official agentskills.io specification: 1-64 characters, lowercase alphanumeric with hyphens, must not start/end with hyphen, no consecutive hyphens. The legacy pattern is preserved for backward compatibility but new code uses OFFICIAL_NAME_PATTERN.
// LEGACY: Too permissive - allows ---, -foo, foo-
export const SKILL_NAME_PATTERN = /^[a-z0-9-]{1,64}$/;
// Official pattern from agentskills.io specification
// - Must start and end with alphanumeric (not hyphen)
// - Single char names allowed (just alphanumeric)
// - Still need separate check for consecutive hyphens (--)
export const OFFICIAL_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
export function validateSkillName(name: string): boolean {
return (
name.length >= 1 &&
name.length <= 64 &&
OFFICIAL_NAME_PATTERN.test(name) &&
!name.includes('--')
);
}
export function validateSkillMetadata(metadata: SkillMetadata): string[] {
const errors: string[] = [];
if (!metadata.name) {
errors.push('name is required');
} else if (!validateSkillName(metadata.name)) {
errors.push('name must be lowercase, hyphens only, max 64 chars');
}
if (!metadata.description) {
errors.push('description is required');
} else if (metadata.description.length > MAX_DESCRIPTION_LENGTH) {
errors.push(`description exceeds ${MAX_DESCRIPTION_LENGTH} chars`);
}
// Validate extends field - check both root (legacy) and extension location
const ext = getExtension(metadata);
const extendsValue = metadata.extends ?? ext.extends;
if (extendsValue !== undefined) {
if (!validateSkillName(extendsValue)) {
errors.push('extends must be a valid skill name');
} else if (extendsValue === metadata.name) {
errors.push('skill cannot extend itself');
}
}
return errors;
}Architecture Philosophy in Code
| Principle | Implementation | Source |
|---|---|---|
| Claude Code compatibility | Official fields at root level, extensions namespaced under metadata.extensions |
SkillMetadata interface |
| Backward compatibility | Legacy root-level fields preserved with @deprecated markers, getExtension() reads from both locations |
getExtension() helper |
| Strict naming | Two-pattern system: legacy permissive + official strict, with consecutive-hyphen guard | validateSkillName() |
| Validation-first | Metadata validated before any write operation, errors collected not thrown | validateSkillMetadata() |
| Self-extension prevention | Skill cannot set extends to its own name |
validateSkillMetadata() |