Kimi Skills: What They Are and How to Build One

Kimi Code CLI skills let you teach the agent a workflow once, then invoke it with plain language. Instead of typing the same instructions every time, you write them down as a skill and Kimi follows them.

I was initially a Claude user, but I recently switched to Kimi and I like it so far. The shell-as-a-first-class-tool model fits the kind of system-level work I do, and skills make that work repeatable.

A skill is just a folder with a clear contract. That contract tells Kimi what the skill does, when to use it, and exactly how to run it. This post explains what skills are, where Kimi finds them, and how to create one from scratch.

What a Kimi skill is

A skill is a reusable capability for Kimi Code CLI. It can be:

• A project template, like scaffolding a Spring Boot service.
• A workflow, like turning a voice recording into a video.
• A set of conventions, like how to review a pull request.
• A domain guide, like how to structure a distributed-systems feature.

Every skill has a SKILL.md file with YAML frontmatter. The frontmatter gives the skill a name and a description. The description is the trigger phrase — Kimi reads it to decide whether the skill matches what the user asked for.

Skills are discovered from several places, with project-level skills taking priority:

• Project: .kimi-code/skills/ or .agents/skills/ in the project root.
• User: ~/.kimi-code/skills/ or ~/.agents/skills/.
• Plugin: skills declared by an installed plugin.
• Built-in: skills shipped with Kimi Code CLI.

Why skills matter

Without skills, every session starts from zero. You describe the same conventions, the same file layout, and the same verification steps over and over.

With skills, you write the instructions once. Kimi loads them when relevant and executes them consistently. A skill is memory that survives across sessions and projects.

For example, my Kimi Voiceover Video skill takes a voice recording and produces a short-form video. The skill defines the whole pipeline — transcription, shot planning, media sourcing, composition, sound design, and render — so I never have to explain it again.

The anatomy of a skill

The simplest skill is a single SKILL.md file. More complex skills add a references/ folder for supporting context. Here is the typical structure.

SKILL.md

The runtime contract. It starts with YAML frontmatter containing name and description, followed by the body that defines inputs, steps, and expected output.

---
name: spring-scaffold
description: "Scaffold a new Spring Boot 4 project following Kimi Development Skills conventions."
---

# Spring Boot Scaffold Skill

Generates a complete, convention-compliant Spring Boot 4 project in one shot.

## Step 0 — Gather inputs
...

Keep the body imperative. One step per phase. Tables and code blocks are better than prose.

references/

Optional files the skill loads for extra context. A reference file holds detailed patterns, version pins, or conventions that would clutter the main skill file.

README.md

For humans discovering the skill on GitHub. It explains what the skill does, how to install it, and how to use it.

AGENTS.md

For developers or AI agents editing the skill itself. It documents repo layout, coding conventions, invariants, and how to verify changes.

.kimi-plugin/plugin.json

If you want to distribute the skill as a plugin, this manifest registers it with Kimi Code CLI. It includes the plugin name, version, description, and the path to the skills folder.

How to create a skill

1. Start with the outcome

Write one sentence: "This skill takes X and produces Y." The clearer the outcome, the better the skill.

Bad: "Help me with Java."

Good: "Scaffold a Spring Boot 4 project with feature-sliced packages, Testcontainers, and CI."

2. Choose the scope

Decide where the skill should live:

• Project-local: useful for team conventions or project-specific workflows. Drop it in .kimi-code/skills/my-skill/SKILL.md.
• User/global: useful for personal workflows you want everywhere. Put it in ~/.kimi-code/skills/my-skill/SKILL.md.
• Plugin: useful for sharing with others. Create a repo with .kimi-plugin/plugin.json and a skills/ folder.

3. Let Kimi write the first draft

You do not have to write the skill by hand. Once you have a clear outcome and scope, describe what you want to Kimi or Kimi Code CLI and ask it to generate the skill structure.

A good prompt looks like this:

Create a Kimi skill called pr-review that reads a pull request diff and checks it against our team's conventions. It should output a structured review with blocking and non-blocking items. Generate the SKILL.md, a references/checklist.md, and a project AGENTS.md update if needed.

Kimi will produce the folder, the frontmatter, the steps, and the verification commands. Your job is to review and refine, not to start from a blank file.

4. Write SKILL.md

Whether you wrote the first draft or Kimi did, make sure the final SKILL.md includes:

• YAML frontmatter with name and description.
• A short intro.
• A step-by-step workflow.
• Code examples or commands where needed.
• Verification commands so the agent can check pins and versions.
• A final report telling the user what was done and what to do next.

5. Add references if needed

If a topic is too large for SKILL.md, move it to references/<topic>.md and tell the skill to load it at runtime.

6. Test it

Place the skill in a scanned directory, start a new Kimi session, and describe the outcome in plain language. Kimi should invoke the skill automatically based on the description. If it does not, make the description more specific or broader.

7. Distribute it

For personal use, a symlink or copy into ~/.kimi-code/skills/ is enough. For teams, package it as a plugin and install it with /plugins install /path/to/repo.

What makes a good skill

• One clear outcome. A skill should do one thing well.
• Plain-language trigger. The description should match how users actually ask for it.
• Imperative steps. Tell Kimi what to do, not what to think about.
• Verifiable defaults. Include the curl command to re-check every version pin.
• Minimal comments. Generated code needs only WHY, never WHAT.
• A next step. Every skill ends by telling the user what to do next.

Example: a tiny skill

Here is a complete, minimal skill that writes a conventional commit message:

---
name: commit
description: "Write a conventional commit message from a short description of the change."
---

# Conventional Commit Skill

Given a short description, produce a commit message in conventional-commit format.

## Inputs

- The change description, e.g. "fix the login timeout bug"

## Output

A single line in this format:

```
<type>(<scope>): <description>
```

Choose type from: feat, fix, docs, style, refactor, test, chore.
Keep the description lowercase and imperative.

## Example

Input: "add user authentication"
Output: "feat(auth): add user authentication"

That is enough. No scripts, no references, no plugin manifest. Drop it into ~/.kimi-code/skills/commit/SKILL.md and say "write a commit for adding dark mode."

If you want to go deeper

My open-source skills are on GitHub if you want working examples:

• Kimi Voiceover Video — a full pipeline skill.
• Development Skills — Spring Boot and backend engineering skills.

Start small. Build one skill for one thing you do twice. Then add another. After a few, you will have a library of repeatable workflows that actually survive between sessions.

You can find more of my work on GitHub.