Skills Management
Relevant source files
The following files were used as context for generating this wiki page:
Skills in OpenWork represent specialized agentic capabilities, workflows, or tool integrations that extend the core functionality of the platform. They are primarily defined as Markdown files (SKILL.md) with YAML frontmatter, allowing agents to understand when and how to trigger specific behaviors based on user intent.
The Skills Management system handles the lifecycle of these capabilities across several scopes: local project directories, global user configurations, and remote repositories known as "Skill Hubs". It provides the infrastructure for discovering, installing, authoring, and sharing skills within a team or the broader community.
Sources: apps/app/src/app/data/skill-creator.md:1-12, apps/server/src/skills.ts:1-20
Architecture and Discovery
OpenWork implements a multi-layered discovery mechanism to aggregate skills from various locations on the host system and remote environments.
Skill Scopes
Skills are categorized by their storage location and accessibility:
| Scope | Location | Description |
|---|---|---|
| Project | .opencode/skills/ | Skills specific to the current workspace. |
| Global | ~/.config/opencode/skills/ | Skills available across all local workspaces. |
| Hub | Remote GitHub Repos | Curated collections of skills installable via the UI. |
| Cloud | OpenWork Cloud / Org | Team-shared skills synchronized via the cloud control plane. |
Sources: apps/server/src/skills.ts:114-135, apps/app/src/react-app/domains/settings/state/extensions-store.ts:60-70
Discovery Flow
The server-side listSkills function scans workspace roots and global configuration directories. It supports both flat layouts and categorized "domain" folders (e.g., skills/<domain>/<name>/SKILL.md).
The discovery process ensures that project-specific skills take precedence over global ones if naming conflicts occur.
Sources: apps/server/src/skills.ts:86-140
Skill Definition and Parsing
A skill is anchored by a SKILL.md file. The system uses a specific Markdown structure to extract metadata required for agent orchestration.
Data Structure
The SkillItem interface represents the parsed state of a skill:
name: Unique identifier for the skill.description: Human-readable summary used by models to understand capability.trigger: Specific phrases or conditions that should activate the skill.path: Absolute filesystem path to the skill definition.scope: Indicates if the skill is project-level or global.
Sources: apps/server/src/skills.ts:57-79
Frontmatter and Triggers
The system parses YAML frontmatter to extract the skill's name and description. If a explicit trigger or when field is missing, it attempts to extract trigger phrases from the body of the Markdown file, specifically looking for sections titled "When to use".
// Example of Skill Frontmatter requirement
const skillTextSchema = z.string().superRefine((value, ctx) => {
if (!hasSkillFrontmatterName(value)) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Skill content must start with frontmatter that includes a name.",
});
}
});
Sources: ee/apps/den-api/src/routes/org/skills.ts:25-40, ee/packages/utils/src/skill-markdown.ts:150-170
Skill Hubs and Cloud Synchronization
OpenWork supports remote "Skill Hubs" (GitHub-backed) and "Cloud Skill Hubs" (Enterprise-managed) for distributing skills across teams.
Remote Hub Installation
The installHubSkill function clones skill definitions from remote repositories into the local workspace. It recursively fetches file trees from the GitHub API and writes them to the .opencode/skills/<name> directory.
Sources: apps/server/src/skill-hub.ts:109-178
Organizational Skills
In enterprise environments, skills can be managed at the organization level. The system provides endpoints for creating "Skill Hubs" within an organization and granting access to specific members or teams.
| Endpoint | Method | Action |
|---|---|---|
/v1/skills | POST | Create a new organization skill. |
/v1/skill-hubs | POST | Create a hub to group skills. |
/v1/skill-hubs/:id/skills | POST | Add an existing skill to a hub. |
/v1/skill-hubs/:id/access | POST | Grant a team/member access to a hub. |
Sources: ee/apps/den-api/src/routes/org/skills.ts:175-185, ee/apps/den-api/src/routes/org/skills.ts:318-350
Authoring and Persistence
The platform provides a "Skill Creator" template and a dedicated editor for authoring new skills.
Content Building
When a skill is created or updated, the buildSkillContent logic ensures the Markdown content is properly formatted with frontmatter that matches the payload metadata. This enforces consistency between the filesystem state and the platform's internal database or cache.
export function buildSkillContent(payload: UpsertSkillPayload): { name: string; content: string } {
const name = payload.name.trim();
validateSkillName(name);
const { data, body } = parseFrontmatter(payload.content);
// ... frontmatter validation and merging ...
const nextDescription = frontmatterDescription || payload.description || "";
const frontmatter = buildFrontmatter({ ...data, name, description: nextDescription });
return { name, content: frontmatter + body.replace(/^\n/, "") };
}
Sources: apps/server/src/skills.ts:147-183
Mutating Local Skills
The upsertSkill and deleteSkill functions manage the physical files in the project directory. Successful mutations often trigger a ReloadReason (specifically "skills") to notify the underlying OpenCode engine to refresh its tool cache.
Sources: apps/server/src/skills.ts:185-212, apps/server/src/server.ts:1140-1160
Conclusion
Skills Management in OpenWork provides a unified interface for extending AI capabilities through a file-based, Markdown-driven architecture. By integrating local discovery with remote GitHub hubs and Enterprise Cloud hubs, the system enables both individual productivity and team-wide automation standards. The emphasis on frontmatter-driven triggers allows agents to dynamically select tools based on user context, while the robust API surface ensures that skills remain auditable and manageable across different deployment environments.
Sources: README.md:95-105, AGENTS.md:5-20