DOCSEARCHbyAlgolia
Submit Docs

SkillPointer

repository·main·Indexed 41 days ago

https://github.com/blacksiders/skillpointer

An organizational pattern and Python script for AI development agents like OpenCode and Claude Code designed to reduce the 'Token Tax'. It implements a Hierarchical Pointer Architecture that moves raw skills into a hidden vault and replaces them with lightweight category pointers to minimize startup token overhead during Level 1 context hydration.

Tokens
798
Snippets
2
Records
4
Agent score
50%

What's inside SkillPointer

  1. How SkillPointer solves the 'Token Tax' problem

    main

    AI agents (like OpenCode and Claude Code) use a 3-level progressive disclosure system for skills:

    1. Level 1 (Startup): The agent automatically loads the name and description of every skill into the <available_skills> block in the system prompt.
    2. Level 2 (Match): When a skill is matched, the full SKILL.md body is loaded.
    3. Level 3 (Reference): Scripts, templates, or linked files are loaded when explicitly referenced.

    The Problem: As the number of skills grows (e.g., 2,000 skills), the Level 1 startup cost becomes massive (~80,000 tokens), which increases API costs, slows response times, and degrades reasoning due to the "lost in the middle" phenomenon.

    The Solution: SkillPointer moves the bulk of skills into a Hidden Vault (unseen by the Level 1 scanner) and replaces them with a small number of Category Pointers. The AI matches a pointer, then uses its native tools (list_dir, view_file) to browse the vault and retrieve the specific skill it needs.

  2. Manually implement SkillPointer architecture

    main

    If you do not want to use the setup.py script, you can manually implement the pointer pattern:

    1. Create a hidden library directory: For example, ~/.opencode-skill-libraries/animation.
    2. Move skills: Place your actual skill folders inside this hidden directory.
    3. Create a Pointer File: Inside your active skills directory (e.g., ~/.config/opencode/skills/animation-category-pointer/), create a SKILL.md file. This file must contain instructions telling the AI to use its native tools to browse the hidden library directory to find specific skills.

  3. Install SkillPointer for OpenCode or Claude Code

    main

    SkillPointer is a zero-dependency Python script that reorganizes your AI agent's skill library into a Hierarchical Pointer Architecture to reduce startup token costs. It moves raw skills into a hidden vault and replaces them with lightweight 'Pointer Skills' that index categories.

    For OpenCode

    Run the setup script without flags. This targets the OpenCode configuration directory and uses a specific vault directory.

    For Claude Code

    Run the setup script with the --agent claude flag. This targets the Claude Code configuration directory and uses a dot-prefixed vault directory (~/.skillpointer-vault) which Claude's scanner naturally skips during Level 1 context hydration.

    # For OpenCode
python setup.py

# For Claude Code
python setup.py --agent claude

  4. Test your SkillPointer installation

    main

    After running the setup script, verify that the AI can navigate the hierarchy by asking it to use a category pointer to find a specific skill.

    Example Prompt:

    "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."

    Expected Behavior in Logs:

    1. The AI performs a Level 2 load of the pointer skill.
    2. The AI uses its native list_dir tool to browse the hidden vault.
    3. The AI uses view_file to read only the specific skill required.
    > "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."