| Guide ID | UG-4 |
|---|---|
| Audience | Developers, SysAdmins |
| Prerequisites | GS-2 (Core Concepts), GS-3 (How It Works) |
| Time | 15 minutes |
| Difficulty | Intermediate |
Configuration Guide
GSD Skill Creator uses a layered configuration system with sensible defaults that can be tuned for your workflow. This guide covers every configurable setting: retention, thresholds, cluster constraints, refinement bounds, integration features, staging, console, and environment variables.
Retention Settings
Pattern retention is bounded to prevent unbounded growth of observation data.
| Setting | Default | Description |
|---|---|---|
maxAgeDays | 90 | Maximum age of observations before automatic pruning |
maxSessions | 1000 | Maximum number of sessions to retain in pattern data |
Observations older than maxAgeDays are pruned on read. When the session count exceeds maxSessions, the oldest sessions are removed first. These limits ensure that pattern detection stays focused on recent, relevant data.
Trigger Thresholds
Thresholds that control when the system suggests new skills, agents, or refinements.
| Threshold | Value | Description |
|---|---|---|
| Skill suggestion | 3+ occurrences | Minimum pattern repetitions before a skill is suggested |
| Agent suggestion | 5+ co-activations | Minimum skill pair activations before agent composition is suggested |
| Stability requirement | 7+ days | Minimum pattern persistence before it qualifies as stable |
| Refinement eligibility | 3+ corrections | Minimum feedback count before refinement is offered |
These thresholds prevent premature suggestions. A pattern must repeat at least 3 times before the system considers it worth codifying into a skill. Agent composition requires stronger evidence: 5+ co-activations over at least 7 days.
Validation Thresholds
Thresholds used by conflict detection, activation scoring, and calibration commands.
| Threshold | Default | Range | Description |
|---|---|---|---|
| Conflict threshold | 0.85 | 0.5-0.95 | Semantic similarity level that triggers conflict detection |
| Activation threshold | 0.75 | 0.5-0.95 | Minimum confidence level for skill activation prediction |
| Too-close-to-call | <2% margin | — | Flags skills that are borderline competitors for the same prompt |
Override thresholds per-command with flags:
# Stricter conflict detection
skill-creator detect-conflicts --threshold=0.90
# Custom activation threshold for tests
skill-creator test run --threshold=0.80After calibration, thresholds are stored in ~/.gsd-skill/calibration/threshold.json. Use skill-creator calibrate history to view the threshold change log.
Cluster Constraints
Settings that control how skills are grouped for agent composition suggestions.
| Setting | Default | Description |
|---|---|---|
minClusterSize | 2 | Minimum number of skills per cluster |
maxClusterSize | 5 | Maximum number of skills per cluster |
minCoActivations | 5 | Minimum co-activation count to link skills |
stabilityDays | 7 | Minimum days a pattern must persist |
Clusters smaller than minClusterSize are not suggested. Clusters larger than maxClusterSize are split into sub-clusters. The minCoActivations and stabilityDays settings filter noise from transient patterns.
Refinement Bounds
Bounded learning guardrails that limit how much a skill can change through automated refinement.
| Setting | Default | Description |
|---|---|---|
minCorrections | 3 | Number of corrections needed before refinement is available |
maxContentChangePercent | 20 | Maximum percentage of content that can change per refinement |
cooldownDays | 7 | Minimum days between refinements of the same skill |
maxDrift | 60% | Maximum cumulative drift from the original skill content |
These constraints are non-negotiable safety guardrails. Even in YOLO mode, refinements always require user confirmation. The 20% change limit per refinement prevents a single feedback cycle from dramatically altering a skill, while the 60% cumulative drift limit ensures skills do not evolve beyond recognition.
Integration Config
The integration config at .planning/skill-creator.json provides per-feature toggles and budget configuration. All fields are validated with Zod schemas; missing fields use sensible defaults.
{
"features": {
"session_observation": true,
"skill_loading": true,
"passive_monitoring": true,
"dashboard_generation": false
},
"token_budget": {
"cumulative_char_budget": 15500,
"profile_budgets": {
"executor": 20000,
"planner": 12000
}
},
"terminal": {
"port": 3001,
"session_name": "gsd-dev",
"auth_mode": "none"
}
}Feature Toggles
| Feature | Default | Description |
|---|---|---|
session_observation | true | Record session patterns to .planning/patterns/sessions.jsonl |
skill_loading | true | Enable automatic skill loading into agent context |
passive_monitoring | true | Track activation events for calibration data |
dashboard_generation | false | Generate planning dashboard on state changes |
Disable features you do not need to reduce filesystem writes and overhead. For example, set session_observation to false if you do not want pattern data collected.
Per-Profile Budgets
Configure different budget limits for different agent profiles. Profile names strip the gsd- prefix for lookup.
{
"token_budget": {
"cumulative_char_budget": 15500,
"profile_budgets": {
"executor": 20000,
"planner": 12000,
"researcher": 8000
}
}
}The priority chain for budget resolution (first match wins):
| Priority | Source | Location |
|---|---|---|
| 1 (highest) | profile_budgets.<profile> | Integration config |
| 2 | cumulative_char_budget | Integration config |
| 3 | SLASH_COMMAND_TOOL_CHAR_BUDGET | Environment variable |
| 4 (fallback) | Default: 15,500 | Built-in |
See Token Budget Management for detailed budget mechanics and monitoring.
Staging Configuration
The staging layer uses filesystem-based configuration at .planning/staging/ for managing items through a workflow pipeline.
| Directory | Purpose |
|---|---|
inbox/ | New items awaiting analysis |
checking/ | Items currently being analyzed |
attention/ | Items requiring human review |
ready/ | Items approved and ready for execution |
aside/ | Items deferred or rejected |
queue.jsonl | Execution queue with 7-state machine |
Items flow through the staging directories as they progress from discovery to execution. The queue.jsonl file tracks execution state with transitions between pending, active, paused, completed, failed, cancelled, and expired states.
Console Configuration
The console message bus at .planning/console/ enables communication between the browser dashboard and GSD.
| Directory | Purpose |
|---|---|
inbox/ | Messages from browser to GSD |
outbox/ | Messages from GSD to browser |
Messages are Zod-validated JSON envelopes with type, payload, and status fields. The console configuration is part of the integration config:
{
"terminal": {
"port": 3001,
"session_name": "gsd-dev",
"auth_mode": "none"
}
}Environment Variables
| Variable | Purpose | Effect |
|---|---|---|
ANTHROPIC_API_KEY | LLM-powered features | Enables Claude-powered conflict suggestions, test generation, deep activation analysis, and refinement generation |
CI | CI environment detection | When set to true, auto-enables JSON output for test run and other commands |
SLASH_COMMAND_TOOL_CHAR_BUDGET | Budget override | Sets cumulative character budget (lower priority than config file settings) |
Features degrade gracefully without ANTHROPIC_API_KEY. Conflict detection falls back to heuristic suggestions, test generation uses description-based patterns, and activation scoring uses local analysis only. The --llm flag on score-activation is the only feature that hard-requires the API key.
Configuration File Locations
| File | Location | Purpose |
|---|---|---|
| Integration config | .planning/skill-creator.json | Feature toggles, budget, terminal settings |
| Calibration data | ~/.gsd-skill/calibration/threshold.json | Calibrated activation thresholds |
| Pattern data | .planning/patterns/sessions.jsonl | Session observations for pattern detection |
| Staging pipeline | .planning/staging/ | Workflow item management |
| Console bus | .planning/console/ | Browser-GSD communication |
| Discovery state | ~/.gsd-skill-creator/discovery/scan-state.json | Incremental scan watermarks |
| Benchmark results | .planning/calibration/benchmark.json | Accuracy measurement history |
What’s Next
- Token Budget Management — Detailed budget mechanics, monitoring, and optimization tips
- Command Reference — CLI commands that use these configuration settings
- Skill Workflows — End-to-end workflows incorporating configuration