Zero-Token Skills Listing - Setup Guide

Zero-Token Skills Listing - Setup Guide

Current Status

✅ The /skills command is working using the shell script fallback ⚠️ Using ~1,000 tokens per call 🎯 Goal: Reduce to 0 tokens using MCP

What's Happening Now

When you run /skills, you see:

⏺ I don't have access to the list_skills MCP tool, so I'll use the shell script fallback:
⏺ Bash(~/bin/list-skills.sh --names-only)

This works, but uses tokens. Let's fix that!

Enable Zero-Token Operation (5 Minutes)

Step 1: Install MCP SDK

pip install mcp

Verify installation:

python3 -c "import mcp; print('✅ MCP SDK installed!')"

Step 2: Run Automated Setup

cd $HOME/Documents/ws/claude-skills/mcp-servers/skills-lister
./setup.sh

The setup script will:

• ✅ Check Python version (needs 3.10+)
• ✅ Verify MCP SDK is installed
• ✅ Make scripts executable
• ✅ Show you the configuration to add
• ✅ Optionally create .claude/mcp.json for you

Step 3: Configure Claude Code

The setup script will generate the configuration. You need to add it to one of:

Option A: Project-specific (recommended for testing)

$HOME/Documents/ws/claude-skills/.claude/mcp.json

Option B: Global (all projects)

~/.claude/mcp.json

The configuration looks like:

{
  "mcpServers": {
    "skills-lister": {
      "command": "python3",
      "args": [
        "$HOME/Documents/ws/claude-skills/mcp-servers/skills-lister/server.py"
      ]
    }
  }
}

Step 4: Restart Claude Code

Exit your current Claude Code session and start a new one. The MCP server will be loaded automatically.

Step 5: Test It!

Run /skills again. You should now see:

✅ Using MCP list_skills tool
⚡ 0 tokens used
⚡ <1 second response

Instead of:

⚠️ I don't have access to the list_skills MCP tool, so I'll use the shell script fallback
📊 ~1,000 tokens used

Verification

To verify the MCP server is configured:

1. Start a new Claude Code session
2. Check the startup logs for MCP server initialization
3. Run /skills - should be instant with 0 tokens
4. You should NOT see "I don't have access to the list_skills MCP tool"

Before and After

Before (Current State)

User: /skills
Claude: I don't have access to the list_skills MCP tool,
        so I'll use the shell script fallback
        [Runs: ~/bin/list-skills.sh --names-only]
        [Uses: ~1,000 tokens]
        [Time: ~2 seconds]

After (With MCP)

User: /skills
Claude: [Silently calls list_skills MCP tool]
        [Uses: 0 tokens]
        [Time: <1 second]
        Lists all 16 skills instantly!

Troubleshooting

"Module not found: mcp"

pip install mcp

"Script not found"

ls -l ~/bin/list-skills.sh
# If missing:
cp $HOME/Documents/ws/claude-skills/scripts/list-skills.sh ~/bin/
chmod +x ~/bin/list-skills.sh

"MCP server not loading"

Check your configuration file:

# For project-specific
cat $HOME/Documents/ws/claude-skills/.claude/mcp.json

# For global
cat ~/.claude/mcp.json

Verify the path to server.py is absolute (no ~, starts with /).

Still seeing "shell script fallback"

1. Verify MCP configuration exists
2. Restart Claude Code completely (exit and relaunch)
3. Check Claude Code logs for MCP initialization errors
4. Try running the server manually to test:

   cd $HOME/Documents/ws/claude-skills/mcp-servers/skills-lister
   python3 server.py
   # Should wait for input (press Ctrl+D to exit)
   

Benefits You'll Get

Once configured:

If you run /skills 10 times per day:

• Token savings: 10,000 tokens/day
• Cost savings: ~$0.03/day = ~$11/year
• Time savings: 10+ seconds/day

Quick Command Reference

# Install MCP SDK
pip install mcp

# Run setup
cd $HOME/Documents/ws/claude-skills/mcp-servers/skills-lister
./setup.sh

# Test shell script
~/bin/list-skills.sh --names-only

# Test MCP server manually
python3 $HOME/Documents/ws/claude-skills/mcp-servers/skills-lister/server.py

# Check configuration
cat $HOME/Documents/ws/claude-skills/.claude/mcp.json

Next Steps After Setup

Once working, you can:

1. ✅ Use /skills with 0 tokens
2. 🚀 Create more MCP servers for other operations
3. 📊 Monitor token savings over time
4. 🎉 Enjoy instant, free skill listings!

Need More Help?

See detailed documentation:

• QUICK-START.md - Quick setup
• INSTALL.md - Detailed installation
• README.md - Full documentation
• ARCHITECTURE.md - How it works

Summary

The MCP server is ready to use! Just need to:

1. pip install mcp
2. Run ./setup.sh
3. Restart Claude Code
4. Enjoy zero-token skill listings! 🎉