Core Principle: The Engineering Practice of “Progressive Disclosure”
In traditional Large Language Model (LLM) application development, developers often inject all tools and rules into the context, causing the system to become increasingly bloated as functionality grows. The OpenCode Skills mechanism addresses this problem with a solution called “Progressive Disclosure”. When the system starts, this mechanism only reveals the name and description metadata fields of each Skill to the model. Only when the user’s task intent semantically matches a Skill’s description does the system load the full definition of that Skill (including execution commands, code paths, etc., contained in the SKILL.md file) into the current context. This “just-in-time loading” approach significantly reduces the context overhead of each interaction, ensures efficient use of computing resources (Tokens), and architecturally supports the infinite expansion of the skill library, avoiding model “memory confusion” or performance degradation caused by too many tools.
Skill Deployment and Priority Management
The OpenCode system discovers and loads Skills by scanning specific directories, following a clear priority hierarchy (from lowest to highest):
- Global Configuration Directory: Shared by all projects in the system, located at
~/.config/opencode/skills/ (Linux/macOS) or C:\\Users\\<username>\\.config\\opencode\\skills\\ (Windows).
- User Home Directory: For compatibility with older configurations, the path is
~/.opencode/skills/.
- Project-Local Directory: Has the highest priority, located under the
.opencode/skills/ path in the current working directory. This method is recommended for team collaboration as it allows Skills to be included with the project code in version control systems like Git, ensuring environment consistency.
Deployment requires adherence to a strict naming convention: a Skill’s directory name must exactly match the name field within its SKILL.md file, using only lowercase letters, numbers, and single hyphens (-), with a length limit of 1-64 characters.
Skill Installation and Invocation Mechanisms
There are two main ways to install Skills: one is by manually downloading pre-made Skill packages from code repositories like GitHub and placing them in the specified directory; the other is by describing requirements to OpenCode in natural language, which then automatically generates the complete skill structure, including the SKILL.md definition, the MCP (Micro-service Communication Protocol) service code acting as the service endpoint, and the requirements.txt dependency file. The invocation mechanism is equally flexible:
- Automatic Triggering: When the user’s input is a high semantic match with a Skill’s
description, the Agent will autonomously decide to execute that skill.
- Manual Specification: To ensure deterministic execution, users can invoke a skill by “mentioning” it with the
@skill-name format, or by directly calling its corresponding tool function in code, such as skills_bookmark_it(url="...").
Users can verify the list of currently loaded skills in the session by running a query like “What skills can I use?”, which is useful for debugging and confirmation.
Practical Analysis: Building an Automated “Web Bookmarking” Skill
Taking the creation of a bookmark-it skill that saves web page content as Markdown as an example, its components clearly demonstrate the Skills workflow:
SKILL.md: Acts as the skill manifest, defining the name and description for discovery and comprehension by the Agent, such as “Scrape the main content of a web page, remove ads/navigation bars, and save as clean Markdown.”- MCP Service: This is the core execution backend of the skill, typically a standalone Python script (e.g.,
bookmark_it_server.py), which uses frameworks like FastMCP and libraries like Playwright to perform the “dirty work” of web scraping, content cleaning, and file generation.
opencode.json: In the project configuration file, the above Python script is registered as a local service via the mcp field, thereby linking the skill’s declaration with its actual execution logic.
This architecture effectively separates the LLM’s decision-making capabilities from the execution capabilities of specific tasks, building a stable, maintainable, and powerful automation workflow.
