blacksiders/skillpointer

SkillPointer is an organizational pattern for AI development agents (OpenCode, Claude Code, and others) that solves a specific scaling problem: when you have hundreds or thousands of skills installed, the startup token cost becomes massive.

It works with the native skill system, not against it - using skills to optimize skills.

---

The “Token Tax” Problem

AI agents like OpenCode and Claude Code use a 3-level progressive disclosure system to load skills:

The problem is Level 1. Even though full skill content loads on-demand, the agent still loads the name and description of every single skill into the system prompt at startup - on every conversation.

With a large library this adds up fast:

• It slows down AI response times - the agent has to parse thousands of skill descriptions before reasoning.
• It inflates API costs - ~80K tokens consumed every single prompt just listing skills.
• It degrades reasoning - research shows LLMs perform worse with longer contexts (“lost in the middle” problem).

---

The Pointer Solution

SkillPointer works with the native skill system by reorganizing your library:

1. Hidden Vault Storage: It moves all raw skills into an isolated directory (~/.opencode-skill-libraries/). The agent’s startup scanner cannot see them here - so they don’t appear in ``.
2. Category Pointers: It replaces 2,000 skills with ~35 lightweight “Pointer Skills” in your active skills/ directory (e.g., security-category-pointer). Each pointer is a native SKILL.md that indexes an entire category.
3. Dynamic Retrieval: When you ask a question, the AI matches the relevant category pointer. The pointer instructs the AI to use its native tools (list_dir, view_file) to browse the hidden vault and read the exact skill file it needs.

Real Measured Results

These numbers are from a live environment with 2,004 skills across 34 categories:

---

Installation & Setup

A zero-dependency Python script that converts your skills directory into a Hierarchical Pointer Architecture.

Step 1: Run the Setup Script

Download and run setup.py. It automatically categorizes your skills into expert domains (e.g., ai-ml, security, frontend, automation) using a keyword heuristic engine.

By default, the script targets OpenCode. You can specify Claude Code using the --agent flag:

For OpenCode:

python setup.py
# Targets: ~/.config/opencode/skills
# Vault: ~/.opencode-skill-libraries

For Claude Code:

python setup.py --agent claude
# Targets: ~/.claude/skills
# Vault: ~/.skillpointer-vault

(Note for Claude Code: The .skillpointer-vault directory is intentionally prefixed with a dot so Claude’s aggressive file scanner natively skips it during Level 1 context hydration).

Step 2: Test It!

Start your AI agent and ask it to fetch a specific skill:

“I want to create a CSS button. Please consult your web-dev-category-pointer first to find the exact best practice from your library before writing the code.”

Watch the execution logs:

1. The AI reads the pointer (Level 2 load - just the pointer body).
2. The AI uses its native list_dir to browse the hidden vault.
3. The AI reads only the specific skill file it needs.
4. It generates expert-level code.

---

Manual Implementation Guide

If you prefer to set this up manually without the setup.py script:

1. Create a hidden library directory (e.g., ~/.opencode-skill-libraries/animation)
2. Place your actual skill folders inside that directory.
3. Create a SKILL.md Pointer File inside your active ~/.config/opencode/skills/animation-category-pointer/ directory that tells the AI where to look. (See the setup script for the optimal pointer prompt formula).

---

FAQ

---

How It Works (Technical Details)

SkillPointer leverages the way AI agents handle skills, as documented by OpenCode and Claude Code:

1. At startup, the agent scans all SKILL.md files and injects their name + description into an `` XML block in the system prompt.
2. SkillPointer moves 2,000 raw skill folders to a hidden vault directory outside the scan path.
3. SkillPointer creates 35 category pointer skills in the scan path. Each pointer’s SKILL.md contains instructions telling the AI to browse the vault using its native file tools.
4. At runtime, the AI matches a pointer, reads its body, follows the instructions, and retrieves exactly the skill it needs from the vault.

No custom tools, no plugins, no API calls. Just smart organization of native skills.

---