Skills

Skills are directories containing a SKILL.md file that teach the agent how to perform specialized tasks. Kodik discovers skills automatically on startup and makes them available to the agent. The agent decides on its own when a skill is relevant and applies it. Users can also invoke skills explicitly via slash commands.

SKILL.md File Format

Each skill is a folder containing a SKILL.md file. Skill metadata is declared in YAML frontmatter:

---
name: my-skill
description: What this skill does and when to use it.
user-invocable: true
disable-model-invocation: false
---

## Overview

Describe the skill's purpose. Write it as instructions the agent should follow.

## Guidelines

- Prefer X
- Always do Y
- Avoid Z

Frontmatter Fields

Field	Required	Description
`name`	Yes	Unique skill identifier (lowercase, hyphens for spaces, max 64 characters). Used for skill lookup and as the slash command name.
`description`	Yes	Description of what the skill does and when to use it. The agent uses this to decide relevance (max 1024 characters).
`user-invocable`	No	Whether the skill appears as a slash command in the `/` menu. Defaults to `true`. Set to `false` to hide the skill from the menu while still allowing the agent to load it automatically.
`disable-model-invocation`	No	Prevents the agent from loading the skill automatically. Defaults to `false`. Set to `true` to restrict the skill to explicit slash command invocation only.

Skill Discovery Locations

Kodik discovers skills from the following locations (listed in descending priority order; when names collide, the higher-priority source wins):

Location	Scope	Priority
`<selected-workspace>/.kodik/skills/`	Selected chat workspace	4
`<selected-workspace>/.agents/skills/`	Read-only compatibility	3
`~/.kodik/skills/`	User (global)	2
`~/.agents/skills/`	Read-only compatibility	1
Plugin skills	Namespaced plugin assets	—

Skills from plugins are namespaced with the plugin id (<plugin-id>:<name>).

In a multi-root window, Kodik reads only the workspace recorded by the selected chat session; it does not merge every open folder. Workspace .agents skills are inventoried in Settings while the workspace is untrusted, but they cannot be added to prompts or invoked until you trust that workspace. Settings and Marketplace never edit or delete .agents content: use Open to inspect it, then copy it into the corresponding lowercase .kodik folder if you want Kodik to own it. Other files under .agents are not active Kodik inputs.

On the first launch of the new storage layout, Kodik moves global ~/.kodik/Skills into lowercase ~/.kodik/skills before opening the workbench. Existing lowercase content wins; exact duplicates deduplicate and conflicts remain inspectable under ~/.kodik/.migration/global-assets-v1/. After the committed cutover, uppercase global or workspace skill folders are inert. Move any folder created there later into the lowercase owner manually.

Kodik does not follow symbolic links inside owned skill or plugin paths. A linked root, category, skill directory, SKILL.md, plugin manifest, or other plugin-owned configuration is reported as inactive so external content cannot silently gain prompt, hook, secret, or application-state ownership. Copy the content into the canonical lowercase folder instead of linking it when you want Kodik to load or manage it.

Identifiers are compared in normalized lowercase form. When the same identifier occurs at different priority levels, the higher entry is active and Settings marks the others as shadowed. Two definitions with the same identifier at the same priority are reported as ambiguous and neither is activated.

How the Agent Applies Skills

On each request the agent receives a list of available skills (name + description). It decides which skills are relevant and loads their content. If a skill has disable-model-invocation: true, the agent never loads it automatically — it is only available via explicit user invocation.

User-Invoked Skills

If a skill has user-invocable: true (the default), it can be invoked by typing /skill-name in the chat input. All available user-invocable skills appear in the / menu. See the slash commands overview for details.

Creating a Skill

To create a skill through the agent, type /create-skill (or /createskill) in the chat input. The command asks for a name and description, then creates a directory with a SKILL.md file in the appropriate location.

The skill structure is minimal — a single folder with a SKILL.md is all that is needed:

.kodik/skills/
└── deploy-app/
    └── SKILL.md

You can optionally add supporting files:

.kodik/skills/
└── deploy-app/
    ├── SKILL.md
    ├── scripts/
    │   └── deploy.sh
    └── references/
        └── REFERENCE.md

Example Skill

---
name: webapp-testing
description: Guide to testing web applications with Playwright. Use when writing or running browser-based tests.
---

# Web Application Testing with Playwright

## Creating Tests

1. Identify the user flow to test
2. Create a test file in the `tests/` directory
3. Use Playwright locators (prefer role-based selectors)
4. Add assertions to verify expected behavior

## Running Tests

\`\`\`bash
npx playwright test
npx playwright test --debug
\`\`\`