# How to Organize Custom Skills Directories in Kimi-CLI: Best Practices and Layout Guidelines

> Organize Kimi-CLI custom skills effectively with best practices. Learn directory structure, SKILL.md requirements, and placement for optimal skill management.

- Repository: [Moonshot AI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
- Tags: best-practices
- Published: 2026-07-22

---

**Organize custom skills in Kimi-CLI by placing each skill in its own top-level directory containing a required [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) file with concise YAML front-matter, optionally supplemented with `scripts/`, `references/`, and `assets/` subdirectories, while storing user skills in `~/.config/agents/skills/` or project-specific skills in `.agents/skills/` to leverage the three-layer discovery hierarchy.**

Kimi-CLI, the open-source AI command-line interface developed by MoonshotAI, discovers and loads skills through a hierarchical merging system defined in [`klips/klip-8-config-and-skills-layout.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/klips/klip-8-config-and-skills-layout.md). Following the canonical directory structure and file organization patterns implemented in [`src/kimi_cli/agents/agentspec.py`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/agents/agentspec.py) ensures fast discovery, minimal context-window usage, and reliable skill triggering.

## Understanding the Three-Layer Discovery Hierarchy

Kimi-CLI implements a prioritized skill discovery mechanism that merges three distinct layers, with later layers overriding earlier ones. This hierarchy is hardcoded in the discovery logic and follows a specific search order:

1. **Built-in layer**: Internal package files located in `src/kimi_cli/skills/…` (auto-loaded for `LocalKaos` and `ACPKaos` agents).
2. **User layer**: Searches `~/.config/agents/skills/` (canonical), then `~/.kimi/skills/`, then `~/.claude/skills/`.
3. **Project layer**: Loads from `.agents/skills/` relative to the current working directory.

To load a single custom directory explicitly without relying on the hierarchy, pass the `--skills-dir <path>` CLI flag. Note that built-in skills still load when supported by the agent type, even when using custom directories.

## Required File Structure and Skill Anatomy

Every skill must reside in its own directory and contain a **mandatory** [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) file at the root. According to the specification in [`src/kimi_cli/skills/skill-creator/SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/skills/skill-creator/SKILL.md), the standard layout follows this structure:

```

skill-name/
├── SKILL.md            # Required: YAML front-matter + markdown body

├── scripts/            # Optional: deterministic code (Python, Bash, etc.)

├── references/         # Optional: large docs, schemas, API specifications

└── assets/             # Optional: templates, images, final output files

```

The [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) file requires two specific YAML front-matter fields:

- **`name`**: The canonical skill identifier (must match the directory name).
- **`description`**: A concise, exhaustive trigger description that helps Kimi decide when to activate the skill.

The markdown body contains procedural instructions and links to bundled resources. Keep the body under approximately 5,000 words; if content exceeds this, split it into separate files within `references/` and link to them from the main [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md).

Kimi-CLI employs **progressive disclosure** to optimize token usage: it first loads only the metadata front-matter, then the body if triggered by the description match, and finally reads bundled resources on demand.

## Organizing Multiple Variants with Flat Reference Hierarchies

When a skill supports multiple domains, frameworks, or cloud providers, maintain a flat reference structure rather than deep nesting. As documented in the skill-creator specification, all reference files should be reachable directly from the top-level [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md):

```

cloud-deploy/
├── SKILL.md                # Generic workflow + provider selector

└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

```

Kimi reads only the specific reference file matching the user’s request (e.g., [`aws.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/aws.md)). Avoid creating subdirectories within `references/` or `scripts/` beyond a single level to ensure the agent can locate files deterministically.

## Optimization Strategies for Lean Skills

Minimize context-window consumption and discovery overhead with these rules derived from the [`src/kimi_cli/skills/skill-creator/SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/src/kimi_cli/skills/skill-creator/SKILL.md) guidelines:

- **Exclude auxiliary documentation**: Do not include [`README.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/README.md), [`CHANGELOG.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/CHANGELOG.md), or other documentation files inside skill directories. These add noise and are never parsed by the agent.
- **Offload large content**: Store reference material exceeding 10,000 words in `references/` and include a grep pattern in [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) so Kimi can decide whether to load the file.
- **Isolate deterministic code**: Place reusable scripts that may be executed without LLM interpretation into the `scripts/` directory.

## Naming Conventions and Directory Standards

Consistency in naming ensures reliable skill triggering across the discovery layers:

- **Directory names**: Use lowercase letters, digits, and hyphens only (e.g., `pdf-processor`, `cloud-deploy`).
- **Name matching**: Keep the folder name identical to the `name` field in [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) front-matter to guarantee correct triggering.
- **Canonical user path**: Prefer `~/.config/agents/skills/` over legacy paths for user-level skills.

## Practical Implementation Example

Create a properly structured skill using the canonical user location:

```bash

# Create the skill directory

mkdir -p ~/.config/agents/skills/pdf-processor
cd ~/.config/agents/skills/pdf-processor

# Create the required SKILL.md with front-matter

cat > SKILL.md <<'EOF'
---
name: pdf-processor
description: "Process PDF files – extract text, rotate pages, merge documents. Use when Kimi needs to manipulate PDFs."
---

# PDF Processor

## Quick start

Extract text:

```python
python -m scripts/extract_text.py <input.pdf>

```

## Advanced operations

- Rotate pages → see [rotate.md](references/rotate.md)
- Merge PDFs → see [merge.md](references/merge.md)
EOF

# Create optional resource directories

mkdir scripts references assets

```

Reference scripts within the skill body using standard execution patterns:

```markdown

# Inside SKILL.md body

Rotate a PDF by invoking the deterministic script:

```bash
python -m scripts/rotate_pdf.py --pages "1,2,3" input.pdf output.pdf

```

```

Load the custom directory via CLI:

```bash
kimi --skills-dir ~/.config/agents/skills

```

## Summary

- **Use the three-layer hierarchy**: Store user skills in `~/.config/agents/skills/` and project skills in `.agents/skills/` to leverage automatic merging and override capabilities.
- **Maintain the required structure**: Every skill directory must contain a [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) with `name` and `description` front-matter fields.
- **Keep it flat**: Place reference files and scripts in single-level `references/` and `scripts/` subdirectories, avoiding deep nesting.
- **Optimize for progressive disclosure**: Keep [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) under 5,000 words, offload large documents to `references/`, and use `scripts/` for executable code.
- **Follow naming standards**: Use lowercase-hyphen names that match the `name` field exactly.

## Frequently Asked Questions

### Where should I store my custom skills in Kimi-CLI?

Store user-level skills in `~/.config/agents/skills/` (the canonical path), though Kimi-CLI also checks `~/.kimi/skills/` and `~/.claude/skills/` for compatibility. For project-specific skills that should be version-controlled with your repository, use `.agents/skills/` in the project root.

### What files are required for a skill to function?

Only [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) is mandatory. This file must contain YAML front-matter with `name` and `description` fields, followed by a markdown body containing instructions. Optional folders (`scripts/`, `references/`, `assets/`) may be added as needed, but the skill will fail to load if [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) is missing.

### How do I handle large reference documents without exceeding context limits?

Place documents larger than 10,000 words in the `references/` subdirectory and mention them in [`SKILL.md`](https://github.com/MoonshotAI/kimi-cli/blob/main/SKILL.md) with specific grep patterns or conditional statements. Kimi-CLI loads resources on demand after checking the metadata and body, so large files remain unloaded until explicitly referenced.

### How does Kimi-CLI resolve conflicts between user and project skills?

Kimi-CLI merges skills from built-in, user, and project layers in that order, with later layers overriding earlier ones. If a skill exists in both `~/.config/agents/skills/` and `.agents/skills/`, the project-level version takes precedence. This allows project-specific customization of shared skill definitions.