Skills

Skills are reusable AI agent capabilities defined as SKILL.md files (Markdown with YAML frontmatter).

Skills are semantically different from Contexts:

• Contexts provide knowledge ("what the agent knows")
• Skills provide capabilities ("what the agent can do")

Two Ways to Use Skills

KubeOpenCode supports two complementary approaches for loading skills:

Approach	How	Best for
File-based (workspace)	Place skills in your project repo's .opencode/skills/ or .agents/skills/ directory	Team-owned skills that live alongside your code
CRD skills[] field	Reference external Git repositories in the Agent spec	Shared/public skills from other repositories

File-based skills (workspace directory)

If your project repository already contains skills in the standard OpenCode directory structure, they are automatically discovered when OpenCode starts — no additional CRD configuration needed. This works identically to running OpenCode locally.

For example, the kubeopencode-agent repository has skills defined at .opencode/skills/:

kubeopencode-agent/
└── .opencode/
    └── skills/
        ├── github-respond/SKILL.md
        ├── opencode-update/SKILL.md
        ├── pr-review/SKILL.md
        ├── slack-respond/SKILL.md
        └── tiny-refactor/SKILL.md

Mount the repo to your workspace root via a Git context, and all skills are loaded automatically:

apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: my-agent
spec:
  workspaceDir: /workspace
  contexts:
  - name: my-project
    type: Git
    git:
      repository: https://github.com/kubeopencode/kubeopencode-agent.git
      ref: main
    mountPath: .    # mounts to /workspace

Since the repo is mounted at the workspace root (/workspace), the .opencode/skills/ directory ends up at /workspace/.opencode/skills/ — exactly where OpenCode expects it. All standard OpenCode configurations (.opencode/, .agents/, AGENTS.md, etc.) work the same way.

External skills (CRD skills[] field)

For skills maintained in separate repositories — such as community skills, organization-wide shared skills, or third-party skill collections — use the skills[] field in the Agent spec. The controller clones these repositories and injects them into OpenCode's skill discovery paths.

Both approaches work side by side. You can have project-local skills in your workspace and reference external skills via the CRD — they are all available to the agent.

Basic Usage

apiVersion: kubeopencode.io/v1alpha1
kind: Agent
metadata:
  name: skilled-agent
spec:
  workspaceDir: /workspace
  serviceAccountName: kubeopencode-agent
  skills:
  - name: official-skills
    git:
      repository: https://github.com/anthropics/skills.git
      ref: main
      path: skills/
      names:
      - frontend-design
      - webapp-testing

Select Specific Skills

Use the names field to include only specific skills from a repository. If omitted, all skills under path are included:

skills:
- name: team-skills
  git:
    repository: https://github.com/my-org/ai-skills.git
    path: engineering/
    names:
    - code-review
    - testing-strategy

Private Repositories

Use secretRef for authentication (same Secret format as Git contexts):

skills:
- name: internal-skills
  git:
    repository: https://github.com/my-org/private-skills.git
    ref: v2.0.0
    secretRef:
      name: github-pat

How It Works

1. The controller clones skill Git repositories via git-init init containers
2. Skills are mounted at /skills/{source-name}/ in the agent pod
3. The controller auto-injects skills.paths into opencode.json
4. OpenCode discovers SKILL.md files and makes them available as slash commands

Skills in Templates

Skills can be defined in AgentTemplates and inherited by Agents. Agent-level skills replace template-level skills (same merge strategy as contexts):

apiVersion: kubeopencode.io/v1alpha1
kind: AgentTemplate
metadata:
  name: base-template
spec:
  workspaceDir: /workspace
  serviceAccountName: kubeopencode-agent
  skills:
  - name: org-standards
    git:
      repository: https://github.com/my-org/standards-skills.git

Field Reference

Field	Type	Default	Description
name	string	(required)	Unique identifier for this skill source
git.repository	string	(required)	Git URL (https://, http://, or git@)
git.ref	string	HEAD	Branch, tag, or commit SHA
git.path	string	(root)	Base directory in repo where skills are located
git.names	[]string	(all)	Specific skill directories to include
git.depth	int	1	Clone depth (1=shallow, 0=full)
git.recurseSubmodules	bool	false	Clone submodules recursively
git.secretRef.name	string	-	Secret for Git authentication