This module provides core JavaScript functions for skill parsing, discovery, and resolution that are shared across platform integrations. It implements the low-level operations for handling SKILL.md files, extracting YAML frontmatter, recursively discovering skills in directory trees, and resolving skill names to file paths according to the three-tier priority system.
For information about how specific platforms use these functions, see Claude Code Integration, OpenCode Integration, and Codex Integration. For details on the skill priority system this module implements, see Skill Priority and Overriding.
The skills-core.js module is located at lib/skills-core.js1-209 and exports five functions that provide platform-agnostic skill management capabilities:
| Function | Purpose | Returns |
|---|---|---|
extractFrontmatter(filePath) | Parse YAML frontmatter from SKILL.md | {name: string, description: string} |
findSkillsInDir(dir, sourceType, maxDepth) | Recursively discover SKILL.md files | Array of skill objects |
resolveSkillPath(skillName, superpowersDir, personalDir) | Resolve skill name to file path with priority | {skillFile, sourceType, skillPath} or null |
checkForUpdates(repoDir) | Check git repository for updates | boolean |
stripFrontmatter(content) | Remove YAML frontmatter from content | string (content only) |
Sources: lib/skills-core.js1-209
Sources: lib/skills-core.js1-209 .opencode/INSTALL.md1-120 docs/README.opencode.md1-331
Each skill is stored as a SKILL.md file within a skill directory. The file must contain YAML frontmatter with name and description fields:
The frontmatter section is delimited by --- markers at the beginning and end. The extractFrontmatter() function parses these fields, while stripFrontmatter() removes the frontmatter block to return only the content.
Sources: lib/skills-core.js6-11 tests/opencode/test-skills-core.sh23-31
Parses YAML frontmatter from a SKILL.md file to extract metadata.
Signature: lib/skills-core.js16
Parameters:
filePath - Absolute path to SKILL.md fileReturns:
{name: string, description: string}{name: '', description: ''} if file cannot be read or frontmatter is invalidImplementation Details:
The function reads the file content and scans line-by-line for YAML frontmatter lib/skills-core.js18-51 It uses a state machine to track whether it's inside the frontmatter block:
inFrontmatter = false initially lib/skills-core.js21---, sets inFrontmatter = true lib/skills-core.js26-29key: value lines using regex /^(\w+):\s*(.*)$/ lib/skills-core.js33---, breaks out of the loop lib/skills-core.js27name and description fields lib/skills-core.js48Error Handling:
All exceptions are caught and result in returning empty strings lib/skills-core.js49-51 This ensures the function never throws, making it safe to call on potentially invalid or missing files.
Sources: lib/skills-core.js16-52 tests/opencode/test-skills-core.sh18-84
Recursively discovers all SKILL.md files in a directory tree.
Signature: lib/skills-core.js62
Parameters:
dir - Directory path to searchsourceType - Label for skill source (e.g., 'personal', 'superpowers', 'project')maxDepth - Maximum recursion depth (default: 3)Returns:
Array of skill objects with structure:
Implementation Details:
The function uses a nested recursive helper lib/skills-core.js67-96:
recurse(currentDir, depth) to traverse directories lib/skills-core.js67SKILL.md file lib/skills-core.js77extractFrontmatter() to get metadata lib/skills-core.js79maxDepth lib/skills-core.js90Sources: lib/skills-core.js54-97 tests/opencode/test-skills-core.sh134-246
Resolves a skill name to its file path, implementing the priority system where personal skills shadow superpowers skills.
Signature: lib/skills-core.js108
Parameters:
skillName - Skill name like "brainstorming" or "superpowers:brainstorming"superpowersDir - Path to superpowers skills directorypersonalDir - Path to personal skills directoryReturns:
{skillFile, sourceType, skillPath} if skill foundnull if skill not found in either locationPriority Resolution Logic:
Implementation Details:
superpowers: prefix and strips it lib/skills-core.js110-111null if skill doesn't exist in either location lib/skills-core.js139The superpowers: prefix acts as an escape hatch to explicitly request the superpowers version of a skill, even if a personal version exists.
Sources: lib/skills-core.js99-140 tests/opencode/test-skills-core.sh248-363 tests/opencode/test-priority.sh1-199
Checks if a git repository has updates available from the remote.
Signature: lib/skills-core.js148
Parameters:
repoDir - Path to git repositoryReturns:
true if updates are available (local branch is behind remote)false if up-to-date, on error, or network unavailableImplementation Details:
The function uses git fetch and git status to check for updates lib/skills-core.js151-156:
It parses the output looking for ## status lines containing [behind ] lib/skills-core.js159-164
Error Handling:
The function wraps all operations in a try-catch lib/skills-core.js149-170 If any error occurs (network down, git error, timeout), it returns false lib/skills-core.js166-169 This ensures the bootstrap process is never blocked by network issues.
The 3-second timeout prevents hanging if the network is slow or unavailable lib/skills-core.js153
Sources: lib/skills-core.js142-170 tests/opencode/test-skills-core.sh365-437
Removes YAML frontmatter from skill content, returning only the markdown body.
Signature: lib/skills-core.js178
Parameters:
content - Full content string including frontmatterReturns:
Implementation Details:
Uses a state machine similar to extractFrontmatter() lib/skills-core.js179-199:
inFrontmatter and frontmatterEnded states lib/skills-core.js180-181--- markers, updates state lib/skills-core.js185-192This is used when injecting skill content into agent context, where the frontmatter metadata is not needed.
Sources: lib/skills-core.js172-200 tests/opencode/test-skills-core.sh86-133
Platform-specific plugins import and use these functions to implement skill discovery and loading:
The OpenCode plugin .opencode/plugins/superpowers.js would import:
It uses these functions to:
using-superpowers skill for bootstrap injectionThe session-start hook hooks/session-start.sh can invoke Node.js scripts that import skills-core for:
Codex can use the module for native skill discovery, calling findSkillsInDir() to populate the available skills list.
Sources: .opencode/INSTALL.md1-120 docs/README.opencode.md1-331
The module has comprehensive unit tests in tests/opencode/test-skills-core.sh1-441 The test suite verifies:
| Test | Verification |
|---|---|
extractFrontmatter | Parses name and description from YAML tests/opencode/test-skills-core.sh18-84 |
stripFrontmatter | Removes frontmatter, preserves content tests/opencode/test-skills-core.sh86-133 |
findSkillsInDir | Discovers skills recursively, handles nesting tests/opencode/test-skills-core.sh134-246 |
resolveSkillPath | Priority resolution, prefix handling tests/opencode/test-skills-core.sh248-363 |
checkForUpdates | Handles network errors gracefully tests/opencode/test-skills-core.sh365-437 |
All tests use inline function definitions rather than imports to avoid ESM module resolution issues in test environments tests/opencode/test-skills-core.sh34-69
Sources: tests/opencode/test-skills-core.sh1-441 tests/opencode/run-tests.sh1-166
All functions follow a graceful degradation strategy:
This ensures the module never crashes platform integrations, even when dealing with invalid files, missing directories, or network issues.
Sources: lib/skills-core.js49-51 lib/skills-core.js65 lib/skills-core.js139 lib/skills-core.js166-169
The module exports all five functions using ES6 export syntax lib/skills-core.js202-208:
Platform integrations can import selectively based on their needs:
Sources: lib/skills-core.js202-209
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.