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

Organize custom skills in Kimi-CLI by placing each skill in its own top-level directory containing a required 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. Following the canonical directory structure and file organization patterns implemented in 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 file at the root. According to the specification in 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 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.

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:

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). 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 guidelines:

• Exclude auxiliary documentation: Do not include README.md, 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 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 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:

# 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
• Merge PDFs → see merge.md EOF

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 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 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}