[FEATURE] System-Level Registration for User-Created Skills (24 custom skills, 3 unregistered)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Summary

We have developed a comprehensive Claude Code skills ecosystem with 24 custom skills stored in ~/.claude/skills/, but only 21 are registered in the system-level <available_skills> configuration. This creates a discovery gap where 3 new skills exist but aren't automatically visible to Claude at session start.

3 Unregistered Skills

• compliance-doc-suite-builder - End-to-end compliance document suite builder
• compliance-policy-generator - Professional compliance policy generation
• syncbackpro - SyncBackPro backup automation and Windows profile management

The Problem

Current Architecture:

1. System Configuration Layer (Platform-controlled) - 21 registered skills visible at session start
2. Filesystem Layer (User-controlled) - ~/.claude/skills/ contains all 24 skills with SKILL.md documentation

Impact:

• Only 21 skills visible automatically; 3 must be manually discovered
• Every new session requires running /init-full workaround command
• Users cannot invoke the 3 unregistered skills directly via slash commands
• Not scalable for team distribution or future skill additions

Current Workaround

We've implemented a temporary manual discovery system:

• Command: /init-full - Manually scans filesystem for all 24 skills
• Scripts: generate-skills-registry.py, install-skill.sh, regenerate-skills-registry.sh, verify-skills.sh
• Registry: ~/.claude/skills-registry.json - Documents all skills with metadata

Limitation: Requires manual execution each session and doesn't expose unregistered skills to the system's official skill list.

Proposed Solution

Please consider one of these options:

Option A: Register the 3 Missing Skills (Recommended)

Add these 3 skills to the system-level <available_skills> configuration in your next release:

<skill>
<name>compliance-doc-suite-builder</name>
<description>End-to-end builder for market-ready professional compliance document suites. Use this skill when building complete compliance documentation packages (environmental, safety, HR, financial) from initial planning through to market-ready delivery.</description>
<location>user</location>
</skill>

<skill>
<name>compliance-policy-generator</name>
<description>Professional compliance policy generation for multi-sector deployment. Use when building compliance documentation suites for businesses requiring regulatory compliance.</description>
<location>user</location>
</skill>

<skill>
<name>syncbackpro</name>
<description>SyncBackPro backup automation and profile management for Windows environments. Use this skill when the user needs to run SyncBackPro backup profiles, analyze logs, create profiles, integrate with automation workflows, troubleshoot issues, or set up cloud backup destinations.</description>
<location>user</location>
</skill>

Option B: Enable Filesystem-Based Auto-Discovery

Implement automatic skill discovery from ~/.claude/skills/ at session start:

• Scan for directories containing SKILL.md files
• Extract metadata from YAML frontmatter
• Automatically add to available skills without manual registration
• Benefits: Scalable, no configuration needed, works for all users

Option C: Document Configuration Access

Provide documentation on how users can:

• Access and modify the <available_skills> configuration themselves
• Register custom skills without administrator intervention
• Manage their own skill ecosystem

Alternative Solutions

Workaround Scripts - Available in ~/.claude/scripts/:

• generate-skills-registry.py - Generates skill registry from filesystem
• install-skill.sh - Adds new skills and updates registry
• regenerate-skills-registry.sh - Rebuilds registry from scratch
• verify-skills.sh - Validates all skills

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

Business Context

Organization: ShieldStage - Compliance documentation platform for Australian small businesses

Use Case: We generate regulatory-compliant documents for businesses requiring environmental, safety, financial, and HR compliance policies. These 3 unregistered skills are essential for our operations.

Impact of Registration:

• ✅ Automatically access all 24 skills at session start
• ✅ No manual discovery commands needed
• ✅ Enable team collaboration without special setup
• ✅ Scalability for future skill additions
• ✅ Leverage full power of Claude Code ecosystem

---

Complete Skill Inventory

System-Registered (21):
brand-guidelines, compliance-doc-suite-builder, compliance-policy-generator, compliance-suite-generator, config-auditor, deployment-master, design-guide, document-suite-qa, docx, idea-validator, launch-planner, marketing-writer, mcp-builder, md-sentinel, pdf, pdf-sentinel, pptx, professional-docx-generator, roadmap-builder, skill-creator, xlsx

Filesystem-Only - Need Registration (3):
compliance-doc-suite-builder, compliance-policy-generator, syncbackpro

Additional Context

Attachments & References

1. Skills Registry JSON - Available at ~/.claude/skills-registry.json (generated 2025-12-02)

• Contains metadata for all 24 skills
• Registration status (registered vs filesystem-only)
• Categorization and file information

1. Workaround Scripts - Available in ~/.claude/scripts/:

• generate-skills-registry.py - Generates skill registry from filesystem
• install-skill.sh - Adds new skills and updates registry
• regenerate-skills-registry.sh - Rebuilds registry from scratch
• verify-skills.sh - Validates all skills

1. Documentation - Each skill includes complete documentation in SKILL.md with YAML frontmatter

---

Questions

1. What is the intended workflow for user-created skills in Claude Code?
2. Are skills meant to be auto-discovered from ~/.claude/skills/, or must all be system-registered?
3. Is there a user-facing method to register custom skills without modifying system configuration?
4. What's the roadmap for filesystem-based skill discovery?

---

Additional Information

• Date Submitted: 2 December 2025
• Claude Code Session: Current
• Urgency: Medium (workaround exists but not scalable)
• Environment: Windows + WSL (Linux), macOS compatible
• Contact: Available for follow-up discussion

---

Expected Outcome

System-level registration of the 3 missing skills or documentation/tooling to enable user-managed skill registration. This will allow us to operate at maximum capacity with all 24 skills automatically available at session start, without requiring manual discovery commands.