Skill Manager

Native Python-based skill management for Claude Code - Zero token overhead!

🎯 Purpose

This skill provides a native Python script that handles skill discovery, enabling/disabling, and permission management WITHOUT requiring LLM parsing. This saves 90% tokens compared to LLM-based skill management.

Token Savings:

LLM-based approach: ~800-1000 tokens (reading 6+ skill files)
This skill: ~50-100 tokens (single script execution)
Savings: 750-900 tokens per operation (90%)

🔧 BASH COMMAND ATTRIBUTION PATTERN

CRITICAL: Before executing EACH python/bash command, MUST output:

🔧 [skill-manager] Running: <command>

Examples:

🔧 [skill-manager] Running: python .claude/skills/skill-manager/scripts/skill-manager.py discover
🔧 [skill-manager] Running: python .claude/skills/skill-manager/scripts/skill-manager.py enable cli-modern-tools
🔧 [skill-manager] Running: python .claude/skills/skill-manager/scripts/skill-manager.py toggle-feature cli-modern-tools eza
🔧 [skill-manager] Running: bash .claude/skills/colored-output/color.sh success "" "Configuration updated"

Why: This pattern helps users identify which skill is executing which command, improving transparency and debugging.

📋 Available Commands

Discover & List Skills

# Discover all skills (formatted output)
python .claude/skills/skill-manager/scripts/skill-manager.py discover

# List all skills
python .claude/skills/skill-manager/scripts/skill-manager.py list

# List only enabled skills
python .claude/skills/skill-manager/scripts/skill-manager.py list --filter enabled

# List only disabled skills
python .claude/skills/skill-manager/scripts/skill-manager.py list --filter disabled

# Output as JSON (for Claude to parse)
python .claude/skills/skill-manager/scripts/skill-manager.py json

Enable/Disable Skills

# Enable a skill
python .claude/skills/skill-manager/scripts/skill-manager.py enable colored-output

# Disable a skill
python .claude/skills/skill-manager/scripts/skill-manager.py disable time-helper

View Skill Details

# Show detailed info about a skill
python .claude/skills/skill-manager/scripts/skill-manager.py status changelog-manager

Export Configuration

# Export current configuration as JSON
python .claude/skills/skill-manager/scripts/skill-manager.py export

🎨 VISUAL OUTPUT FORMATTING

Use colored-output skill for headers and results only (2 calls max):

# START: Header only
bash .claude/skills/colored-output/color.sh skill-header "skill-manager" "Managing skills..."

# MIDDLE: Run Python script (produces formatted output)
python .claude/skills/skill-manager/scripts/skill-manager.py list

# END: Result only (if needed)
bash .claude/skills/colored-output/color.sh success "" "Configuration updated!"

🚀 Usage Workflow

When User Invokes: `/cs-skill-management`

Step 1: Run discovery script

python .claude/skills/skill-manager/scripts/skill-manager.py json

Output (JSON):

[
  {
    "skill_name": "changelog-manager",
    "name": "changelog-manager",
    "description": "Update project changelog...",
    "version": "2.8.0",
    "author": "Claude Code",
    "tags": ["changelog", "versioning"],
    "auto_activate": true,
    "enabled": true,
    "permissions": [
      "Skill(changelog-manager)",
      "Bash(python scripts/generate_docs.py:*)"
    ]
  },
  ...
]

Step 2: Parse JSON and present interactive menu

Claude receives the JSON, parses it instantly (no file reads needed!), and displays:

⚙️  Skill Management - Interactive Mode
========================================

Available Skills: 7 total
├─ Enabled: 4 skills
├─ Not Configured: 3 skills
└─ Categories: Release, CLI, Documentation, Time, Output, Development

1. View All Skills (7)
2. View Enabled Skills (4)
3. View Not Configured Skills (3)
4. Browse by Category
5. Search for Skill

🔧 Quick Actions:
6. Enable a Skill
7. Disable a Skill
8. Configure Skill Permissions
9. View Skill Details

Enter choice (1-9) or 'q' to quit:

Step 3: Execute user choice

If user chooses "6. Enable a Skill":

# User selects: colored-output
python .claude/skills/skill-manager/scripts/skill-manager.py enable colored-output

Output:

✅ Enabled: colored-output

Settings.local.json is automatically updated!

🔧 Quick Actions (Argument-Based)

Users can also call the slash command with arguments for instant actions:

# Quick enable
/cs-skill-management enable colored-output

# Quick disable
/cs-skill-management disable time-helper

# Quick status
/cs-skill-management status changelog-manager

# Quick list
/cs-skill-management list enabled

Implementation:

# Claude detects arguments and calls:
python .claude/skills/skill-manager/scripts/skill-manager.py enable colored-output

📊 Script Capabilities

Discovery

Scans .claude/skills/ directory
Parses YAML frontmatter from skill.md files
Extracts: name, description, version, author, tags, auto-activate
Checks enabled status from settings.local.json
Identifies all permissions related to each skill

Enable/Disable

Adds/removes Skill(skill-name) from settings.local.json
Identifies and removes related permissions (e.g., Bash permissions)
Validates JSON before saving
Provides clear success/error messages

Status & Details

Shows comprehensive skill information
Lists all permissions
Shows enabled/disabled status
Displays tags, version, author

Export

Exports full configuration as JSON
Can be used for backup/restore workflows
Portable configuration format

🎯 Integration with /cs-skill-management Command

The slash command .claude/commands/cs-skill-management.md should be updated to:

**When user invokes `/cs-skill-management [args]`:**

1. **Parse arguments** (if any)
2. **Run Python script** with appropriate action
3. **Display results** to user
4. **Handle interactive menu** (if no arguments)

**Examples:**

- `/cs-skill-management` → Interactive menu
- `/cs-skill-management enable colored-output` → Quick enable
- `/cs-skill-management list enabled` → Quick list

⚡ Token Efficiency

Before (LLM-based):

Read 7 skill.md files (30 lines each) = ~600 tokens
Read settings.local.json = ~50 tokens
Parse and format = ~150 tokens
Total: ~800 tokens

After (Script-based):

Run Python script = ~30 tokens
Parse JSON output = ~20 tokens
Total: ~50 tokens

Savings: 750 tokens (94% reduction)

🛠️ Implementation Notes

Auto-Detection of Project Root

The script automatically finds the project root by searching for .claude/ directory:

current = Path.cwd()
while current != current.parent:
    if (current / '.claude').exists():
        self.project_root = current
        break
    current = current.parent

Cross-Platform Compatibility

Uses pathlib.Path for Windows/Mac/Linux compatibility
Pure Python (no external dependencies)
Works with Python 3.6+

Error Handling

Validates JSON before saving
Handles missing files gracefully
Provides clear error messages
Safe fallbacks for parsing errors

YAML Parsing

Simple frontmatter parser (no external deps):

Extracts YAML between --- markers
Parses key: value pairs
Handles arrays in tags field
Falls back to defaults on errors

📝 Customization Points

Adding New Actions

To add new script actions, modify skill-manager.py:

# Add to argument choices
parser.add_argument('action',
                   choices=['discover', 'list', 'enable', 'disable',
                            'status', 'export', 'json', 'YOUR_ACTION'],
                   help='Action to perform')

# Add handler in main()
elif args.action == 'YOUR_ACTION':
    manager.your_custom_method()

Custom Filtering

Add custom skill filters:

def list_skills(self, filter_type: str = 'all') -> None:
    skills = self.discover_skills()

    if filter_type == 'by-tag':
        # Custom tag-based filtering
        skills = [s for s in skills if 'your-tag' in s['tags']]

🔍 Example Output

Discover Command

$ python .claude/skills/skill-manager/scripts/skill-manager.py discover

📋 Skills (7 total)

✅ changelog-manager (v2.8.0)
   Update project changelog with uncommitted changes
   Permissions: 4 configured

✅ cli-modern-tools (v1.0.0)
   Auto-suggest modern CLI tool alternatives
   Permissions: 1 configured

⬜ colored-output (v1.0.0)
   Centralized colored output formatter
   Permissions: 0 configured

...

Status Command

$ python .claude/skills/skill-manager/scripts/skill-manager.py status changelog-manager

📊 Skill Details: changelog-manager
============================================================

Basic Info:
  Name: changelog-manager
  Version: 2.8.0
  Description: Update project changelog with uncommitted changes
  Author: Claude Code

Status:
  ✅ Enabled
  Auto-activate: Yes

Permissions (4):
  ✅ Skill(changelog-manager)
  ✅ Bash(python scripts/generate_docs.py:*)
  ✅ Bash(git tag:*)
  ✅ Bash(git commit:*)

Tags:
  changelog, versioning, git, release-management

📦 File Structure

.claude/skills/skill-manager/
├── skill.md                    # This file (skill instructions)
├── scripts/
│   └── skill-manager.py        # Native Python script
└── README.md                   # User documentation (optional)

🚀 Future Enhancements

Potential additions:

Interactive TUI - Use rich or textual for terminal UI
Skill Templates - Generate new skills from templates
Dependency Management - Track skill dependencies
Backup/Restore - Automatic backup before changes
Import Config - Import exported configurations
Batch Operations - Enable/disable multiple skills at once
Search - Full-text search across skill descriptions

Version History

v1.0.0

Initial release
Native Python implementation
Skill discovery and parsing
Enable/disable functionality
Status and details display
JSON export
Cross-platform support
Zero external dependencies