| name | skill-integration |
| description | Manages skill-creator integration with GSD workflows including skill loading, session observation, bounded learning guardrails, and pattern detection. Use this skill whenever: executing any GSD phase (to ensure relevant skills are loaded first), starting or resuming a work session (to check for pending suggestions), the user asks about skills, patterns, or skill-creator status, performing code changes that might represent repeating patterns, the user corrects Claude's output (highest-signal observation), or when skill refinement, creation, or suggestion review is discussed. Critical for maintaining the adaptive learning layer.
|
| user-invocable | true |
| version | 1.0.0 |
| format | "2025-10-02T00:00:00.000Z" |
| triggers | ["Manages skill-creator integration with GSD workflows including skill loading, session observation, bounded learning guardrails, and pattern detection"] |
| updated | "2026-04-25T00:00:00.000Z" |
| status | ACTIVE |
Skill-Creator Integration
Manages skill loading, observation, and bounded learning for the GSD ecosystem. Ensures learned knowledge persists across sessions and subagent contexts.
Skill Loading Before GSD Phases
Before executing any GSD phase, load relevant generated skills:
- Check
.claude/commands/ for project-level skills
- Check
~/.claude/commands/ for user-level skills
- Project-level skills take precedence over user-level on conflict
- Load only skills relevant to the current phase and task
- Respect the token budget: 2-5% of context window maximum
Critical: When forking subagent contexts for GSD phases (execute-phase, verify-work), include relevant skills in the subagent's context. Clean context means free of stale conversation history -- not free of learned knowledge. A subagent that can't access learned skills is throwing away everything skill-creator has captured.
For full 6-stage pipeline details, see references/loading-protocol.md.
Token Budget Management
The 6-stage skill loading pipeline (Score, Resolve, ModelFilter, CacheOrder, Budget, Load) manages what gets loaded. When multiple skills compete for budget:
- Phase-relevant skills get priority (e.g., testing skills during
verify-work)
- Recently activated skills rank higher than dormant ones
- Project-level skills override user-level duplicates
- If budget is exceeded, queue overflow skills and note what was deferred
Session Observation Protocol
During all work sessions, maintain awareness of patterns worth capturing:
- Tool sequences that repeat across sessions (e.g.,
git log -> read file -> edit -> test -> commit)
- File patterns consistently touched during specific GSD phases
- Commands run after test failures or verification issues
- Corrections the user makes to agent output -- these are the highest-signal observations
- Phase outcomes: success, failure, partial, and what was different
If .planning/patterns/ exists, record observations to sessions.jsonl in that directory. This data feeds skill-creator's pattern detection pipeline.
For observation taxonomy, signal strength ranking, and JSONL schema, see references/observation-patterns.md.
Bounded Learning Guardrails
These constraints are NON-NEGOTIABLE:
- Maximum 20% content change per skill refinement
- Minimum 3 corrections before a refinement is proposed
- 7-day cooldown between refinements of the same skill
- All refinements require user confirmation
- Skill generation never skips permission checks
- Agent composition requires 5+ co-activations over 7+ days
For rationale and enforcement details, see references/bounded-guardrails.md.
Phase Transition Hooks
After completing any GSD phase transition, check for skills that should trigger:
| GSD Event | Check For |
|---|
plan-phase completes | Skills triggered by planning completion, docs regeneration |
execute-phase completes | Skills triggered by execution progress, state updates |
verify-work completes | Skills triggered by verification results, test patterns |
complete-milestone completes | Skills triggered by milestone completion, docs finalization |
Any .planning/ file write | Dashboard regeneration if gsd-planning-docs skill is installed |
Run matching skills after the phase completes, not during -- avoid adding overhead to the critical path.
Skill Suggestions
At the start of each new session, check skill-creator for pending suggestions. If suggestions exist with high confidence (3+ pattern occurrences), briefly notify the user:
"skill-creator detected a repeating pattern: [brief description]. Run skill-creator suggest to review."
Never auto-apply suggestions. Always require explicit user confirmation. This is a core safety principle of the bounded learning system.
When to Suggest skill-creator
Suggest skill-creator when:
- You notice the same sequence of steps has occurred 3+ times
- The user corrects the same kind of output repeatedly
- A workflow is complex enough to benefit from codification
- The user asks "why do I keep having to tell you this?"
Suggest naturally:
I've noticed we run the same lint -> test -> fix cycle after every code change.
Want me to capture this as a skill so it happens automatically?
Auditing a Skill (counterfactual)
Pass-rate is blind to most skill effects — a skill can change behavior in hundreds of ways while pass-rate barely moves. When a skill is created, modified, or proposed for retirement, run the skill-counterfactual-audit skill before finalizing. It runs a paired probe (the same task once with the skill loaded and once without), segments and aligns both traces into goal-directed phases, and emits a SIP report (surface anchoring, template copy, excess planning, task recovery, off-task artifact). Treat its findings as the behavioral-impact signal pass-rate cannot give you: a low-impact skill is a retirement candidate; a high-negative-impact skill needs revision, not just a green test. This is the audit gate for the skill lifecycle this skill manages.
Anti-Patterns
- Do not execute GSD phases without checking for relevant learned skills first
- Do not auto-apply skill suggestions -- always require user confirmation
- Do not load skills that exceed the token budget -- defer and note what was skipped
- Do not ignore user corrections -- they are the primary signal for skill refinement
