Why This Matters
When a skill fails to load, the developer currently sees a generic warning with no guidance on how to fix it. They have to read framework source code to understand what went wrong. Structured error codes with actionable remediation ("SKILL_PARSE_ERROR: unquoted colon in description — wrap the value in quotes") turn a 30-minute debugging session into a 30-second fix. This is table stakes for developer experience in any plugin system.
Context
Implements PRD requirements DX-1, DX-2, DX-3 from docs/skill-registry-prd.md §7.5.
Parent issue: #6330
Current State
The skill system uses generic logger.warning() and logger.error() calls. There are no structured error codes, and error messages don't consistently include remediation guidance.
What's Needed
DX-1: Structured Error Codes (P0)
Define a set of error codes for the skill system:
| Code |
Meaning |
SKILL_NOT_FOUND |
Referenced skill not in catalog |
SKILL_PARSE_ERROR |
SKILL.md YAML parsing failed |
SKILL_ACTIVATION_FAILED |
Skill activation failed (file read error, etc.) |
SKILL_MISSING_DESCRIPTION |
SKILL.md has no description field |
SKILL_YAML_FIXUP |
YAML was auto-fixed (unquoted colons) |
SKILL_NAME_MISMATCH |
Name doesn't match directory |
SKILL_COLLISION |
Name collision resolved |
DX-2: Actionable Error Messages (P0)
Every error should include:
- What failed: specific skill name and path
- Why: root cause (parse error, missing field, etc.)
- Suggested fix: concrete next step
DX-3: Startup Summary (P0)
Already partially implemented (log_active_skills()). Enhance to include:
- Per-skill:
{name, scope, status: loaded|disabled|error}
- Summary line:
Skills: 6 default (5 active, 1 disabled), 3 community (2 catalog, 1 pre-activated)
Acceptance Criteria
Why This Matters
When a skill fails to load, the developer currently sees a generic warning with no guidance on how to fix it. They have to read framework source code to understand what went wrong. Structured error codes with actionable remediation ("SKILL_PARSE_ERROR: unquoted colon in description — wrap the value in quotes") turn a 30-minute debugging session into a 30-second fix. This is table stakes for developer experience in any plugin system.
Context
Implements PRD requirements DX-1, DX-2, DX-3 from
docs/skill-registry-prd.md§7.5.Parent issue: #6330
Current State
The skill system uses generic
logger.warning()andlogger.error()calls. There are no structured error codes, and error messages don't consistently include remediation guidance.What's Needed
DX-1: Structured Error Codes (P0)
Define a set of error codes for the skill system:
SKILL_NOT_FOUNDSKILL_PARSE_ERRORSKILL_ACTIVATION_FAILEDSKILL_MISSING_DESCRIPTIONSKILL_YAML_FIXUPSKILL_NAME_MISMATCHSKILL_COLLISIONDX-2: Actionable Error Messages (P0)
Every error should include:
DX-3: Startup Summary (P0)
Already partially implemented (
log_active_skills()). Enhance to include:{name, scope, status: loaded|disabled|error}Skills: 6 default (5 active, 1 disabled), 3 community (2 catalog, 1 pre-activated)Acceptance Criteria