SkillPointer Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The SkillPointer Architecture defines the structural and behavioral framework for "Skills" within the OpenCode ecosystem. These skills are modular knowledge packages designed to transform general-purpose AI agents into domain-specific experts. The architecture facilitates procedural knowledge, SDK expertise, and domain-specific context through a standardized directory structure and metadata-driven triggering system.
Sources: bundled-skills/skill-creator-ms/SKILL.md:13-18, bundled-skills/writing-skills/references/standards/README.md:1-5
Core Structural Framework
The architecture relies on a strict hierarchical directory and file naming convention to ensure discoverability and consistency. Every skill must reside in a dedicated directory named using kebab-case, which must match the name field in the skill's metadata.
Directory Organization
Skills are organized into three primary tiers based on complexity:
- Tier 1 (Simple): Single file, under 200 lines.
- Tier 2 (Expanded): Multi-concept, 200-1000 lines.
- Tier 3 (Platform): Massive platforms with 10+ products.
Sources: bundled-skills/writing-skills/references/standards/README.md:7-13, bundled-skills/writing-skills/SKILL.md:11-14
Standard File Components
| File | Requirement | Purpose |
|---|---|---|
SKILL.md | Mandatory | The primary entry point containing metadata and core instructions. |
references/ | Optional | Supporting documentation used for progressive disclosure of complexity. |
scripts/ | Optional | Executable code for deterministic operations. |
examples/ | Optional | Concrete usage examples and anti-patterns. |
Sources: bundled-skills/writing-skills/references/standards/README.md:8-12, bundled-skills/skill-creator-ms/SKILL.md:42-48, bundled-skills/skill-creator/SKILL.md:155-165
Metadata and Triggering Logic
The SkillPointer Architecture utilizes YAML frontmatter in the SKILL.md file to drive the "on-demand" loading mechanism. This ensures context efficiency by only loading full skill content when specific trigger conditions are met.
The Trigger Mechanism
The description field in the frontmatter is the critical trigger mechanism. It must start with "Use when..." followed by specific symptoms or situations. Keywords are also explicitly defined in metadata.triggers to assist the LLM in discovery.
Sources: bundled-skills/writing-skills/references/standards/README.md:40-48, bundled-skills/skill-creator-ms/SKILL.md:52-54
The diagram above illustrates the progressive disclosure and triggering flow of the SkillPointer Architecture. Sources: bundled-skills/writing-skills/references/standards/README.md:52-55, bundled-skills/skill-creator-ms/SKILL.md:32-37
Lifecycle and Workflow Orchestration
The creation and maintenance of skills follow a standardized lifecycle orchestrated by the skill-writer and skill-creator modules. This workflow is designed to maximize high-value input coverage and minimize blind spots.
Skill Creation Lifecycle
- Discovery & Planning: Identify trigger conditions and skill type (e.g., Reference, Technique, Pattern).
- Synthesis: Collect and score relevant sources (SDK package names, documentation URLs).
- Authoring: Write the
SKILL.mdin imperative voice. - Validation: Run YAML and content checks against repository standards.
- Registration: Create symlinks in category-specific directories for global discovery.
Sources: bundled-skills/skill-writer/SKILL.md:33-70, bundled-skills/skill-creator/SKILL.md:73-85, bundled-skills/skill-creator-ms/SKILL.md:113-118
Workflow Patterns
For process-heavy skills, the architecture supports specific orchestration patterns:
Sequence diagram showing the automated creation and registration of a new skill. Sources: bundled-skills/skill-creator/SKILL.md:88-100, bundled-skills/skill-creator-ms/SKILL.md:144-150
Advanced Capabilities and Future Directions
The architecture includes provisions for dynamic updates and quality enforcement to ensure long-term maintenance of the skill collection.
Enforcement and Analytics
The system supports different enforcement levels, such as "suggest" for development or "block" for CI/CD pipelines. Future enhancements include dynamic rule updates to avoid restarts and skill analytics to track trigger frequency and false-positive rates.
Sources: bundled-skills/skill-developer/ADVANCED.md:4-44
Implementation Example: Metadata Configuration
The following configuration illustrates a standard Tier 1 skill metadata block:
---
name: azure-ai-agents-py
description: |
Azure AI Agents SDK for Python. Use when creating or managing AI agents.
metadata:
category: foundry
triggers: azure agents, create agent, agent workflow
---
Sources: bundled-skills/skill-creator-ms/SKILL.md:164-170
Conclusion
The SkillPointer Architecture provides a scalable, metadata-driven solution for extending AI agent capabilities. By enforcing strict structural standards and utilizing a progressive disclosure model, it maintains context efficiency while providing deep, domain-specific expertise through modular skill packages.
Sources: bundled-skills/skill-creator-ms/SKILL.md:27-38, bundled-skills/wiki-architect/SKILL.md:46-52