Pointer Generator

The Pointer Generator is a core architectural component responsible for creating lightweight "pointer skills" that bridge the gap between a high-volume skill vault and the active skill environment. Its primary purpose is to keep the initial startup context of the AI agent minimal by offloading full skill implementations into a hidden vault while maintaining discoverability through categorized index files.

By scanning the vault and generating pointer files, the system ensures that the agent can identify relevant specialized skills via keyword searches without the performance penalty of loading every full SKILL.md file into the active context.
Sources: src/skill-pointer/pointer-generator.ts:44-50, src/skill-pointer/pointer-generator.ts:25-30

Architecture and Core Logic

The Pointer Generator operates by organizing skills from an index into specific categories and then writing metadata-rich Markdown files into the active skills directory.

Categorization and Mapping

The system uses a Map<string, SkillIndexEntry[]> to group skills based on their assigned category. If a skill lacks a category, it is assigned to a default uncategorized group. This mapping is the foundation for generating one pointer file per category.
Sources: src/skill-pointer/pointer-generator.ts:54-60, src/constants/constants.ts

Pointer Generation Workflow

The generation process follows a strict sequence to maintain directory integrity and up-to-date metadata:

1. Syncing Pointers: The system identifies expected pointers based on the current index and removes any obsolete directories in the active skills folder that no longer match the index.
2. Directory Preparation: For every category, a new pointer directory is created (if not present) using the ensureDir utility.
3. Content Construction: The generator builds a Markdown string containing YAML frontmatter and a list of all skills available in that category.
   Sources: src/skill-pointer/pointer-generator.ts:65-75, src/skill-pointer/pointer-generator.ts:77-88

This diagram illustrates the logical flow of the generatePointers function.
Sources: src/skill-pointer/pointer-generator.ts:52-89

Data Structures and Configuration

The generator relies on specific interfaces and constants to define the structure of the pointers and the location of source files.

Key Data Structures

Content Metadata

Every generated pointer includes specific YAML frontmatter to assist the agent in discovery:

• name: The category name combined with the pointer suffix.
• description: A summary stating the number of specialized skills in the library and a trigger instruction.
• risk: Set to none as these are informational pointers.
  Sources: src/skill-pointer/pointer-generator.ts:20-24, src/skill-pointer/pointer-generator.ts:46-49

Vault Integration and Interaction

The "Pointer" acts as a map for the agent to access the "Vault." The generated content explicitly instructs the agent on how to retrieve the full implementation.

This sequence diagram shows how the Pointer Generator enables late-loading of heavy skill content.
Sources: src/skill-pointer/pointer-generator.ts:32-41, bundled-skills/writing-skills/references/standards/README.md

Instruction Format

The pointer content provides a three-step instruction for the AI:

1. Identify: Find the skill name in the provided list.
2. Load: Use the view_file tool to read the specific path.
3. Follow: Execute the implementation found in the vault.
   Sources: src/skill-pointer/pointer-generator.ts:32-38

Implementation Details

The core logic for writing the pointer is encapsulated in buildPointerContent. It normalizes paths to ensure cross-platform compatibility (converting backslashes to forward slashes) and formats the category title using title-case.

Pointer Content Snippet

const normalizedPath = libraryPath.replace(/\\/g, "/");
const skillList = skills
  .map((s) => `- **${s.id}** — ${s.description || s.name}`)
  .join("\n");
// Generates the Markdown list used for keyword resolution

Sources: src/skill-pointer/pointer-generator.ts:14-19

The Pointer Generator is critical for maintaining a scalable documentation system. By ensuring that only metadata is loaded initially, it prevents context exhaustion while keeping 100% of the vault's specialized knowledge accessible to the agent.
Sources: bundled-skills/skill-developer/SKILL.md, src/skill-pointer/pointer-generator.ts:46-50