Configuration Loader
Relevant source files
The following files were used as context for generating this wiki page:
The Configuration Loader is a core infrastructure component responsible for the discovery, ingestion, and validation of skill-related configurations within the opencode-skills-collection repository. It serves as the primary interface between the physical file system (where skills are stored as Markdown files and metadata) and the runtime environment that utilizes these skills to perform specialized tasks.
The loader ensures that all skills conform to established metadata standards, such as specific YAML frontmatter requirements and directory naming conventions. By providing a centralized mechanism for configuration management, it enables the system to dynamically load and update capabilities without manual hardcoding.
Architecture and Discovery
The Configuration Loader operates by scanning specific directory structures to identify valid skill definitions. It supports both project-local and global skill locations, allowing for flexible deployment and development workflows.
Directory Scanning Logic
The loader expects a specific hierarchy to recognize a valid skill. Each skill must reside in its own directory, named using kebab-case, which must contain a SKILL.md file as its primary definition.
The diagram shows the dual-path discovery process for local and global skill repositories.
Sources: bundled-skills/writing-skills/references/standards/README.md
Data Structure and Validation
The Configuration Loader enforces strict structural requirements on the files it processes. This validation ensures that agents can correctly discover and trigger skills based on user input.
Frontmatter Metadata
Every skill configuration must include a YAML frontmatter block. The loader extracts key fields to populate the skill registry.
| Field | Requirement | Purpose |
|---|---|---|
name | Must match directory name | Unique identifier for the skill |
description | Under 500 characters | Discovery text for the agent |
metadata.triggers | Comma-separated list | Specific keywords that activate the skill |
metadata.category | String | Classification (e.g., technique, reference) |
Sources: bundled-skills/writing-skills/references/standards/README.md
Validation Rules
The loader applies the following rules during the ingestion phase:
- Case Sensitivity: The filename must be exactly
SKILL.mdin all caps. - Naming Alignment: The
namefield in the frontmatter must be identical to the parent directory name. - Trigger Invariants: Triggers must be listed under the
metadatablock to be searchable.
Sources: bundled-skills/writing-skills/references/standards/README.md
Skill Loading Sequence
The loading sequence involves reading the file content, separating metadata from instructions, and preparing the skill for context injection.
This sequence illustrates the transformation of raw file data into a structured skill object ready for use by the agent.
Sources: bundled-skills/writing-skills/references/standards/README.md, bundled-skills/wiki-architect/SKILL.md
Configuration Efficiency
To minimize token usage and improve performance, the Configuration Loader implements a progressive loading strategy. It only loads the primary SKILL.md into the immediate context, leaving detailed supporting documentation in subdirectories like references/ or examples/.
Context Optimization
The loader enforces a soft limit of 500 lines for the main SKILL.md file. If a configuration exceeds this, the loader is designed to reference external supporting files rather than ingesting them entirely.
- Primary Path:
SKILL.md(Overview and navigation) - Supporting Path:
references/*.md(Detailed patterns and troubleshooting)
Sources: bundled-skills/writing-skills/references/standards/README.md
Conclusion
The Configuration Loader is the foundational system that enables the modularity of the opencode-skills-collection. By enforcing strict standards on directory structures and metadata frontmatter, it provides a reliable and efficient way for the agent to discover and utilize specialized domain knowledge.