Skills and Project Rules

Skills are reusable instruction sets that extend what the Kimchi agent can do. Each skill is a directory containing a SKILL.md file — a markdown document with YAML frontmatter and a body of instructions. When the agent recognizes a matching task or a user invokes a skill via a slash command, it loads and follows the skill's instructions.

Skills differ from project rules. Skills activate on demand for specific tasks; project rules (AGENTS.md, CLAUDE.md, and Cursor rules) apply to every session in a repository as standing guidelines.

Skill Directories

Kimchi scans several directories for skills. When the same skill name appears in multiple locations, the first match wins.

Project skill scoping

Kimchi searches for .kimchi/skills/ starting from the directory where it was launched and walks up toward the filesystem root, stopping at the first match. This means you can place skills at different levels of a directory tree and Kimchi will automatically use the closest one.

Only the nearest match is loaded — if a .kimchi/skills/ exists in a subdirectory, Kimchi uses that and does not also load one from a parent directory. To make skills available regardless of where Kimchi is launched, add the shared path as a custom skill directory.

Cross-agent compatibility

If you already maintain skills for another coding agent, Kimchi picks them up automatically — no duplication needed. For each agent directory, Kimchi checks the project-local path first (e.g., <project>/.cursor/skills/), then falls back to the home directory (e.g., ~/.cursor/skills/). Claude Code skills require the extension to be enabled: run kimchi resources enable extensions.claude-code-skills and restart Kimchi.

Skills follow the open Agent Skills specification, making them portable across coding agents that support the format.

Adding custom skill directories

To add a custom skill directory, run kimchi setup and select it during the skills configuration step. The setup wizard also offers the option to add a custom path.

You can also edit ~/.config/kimchi/config.json directly and add paths to the skillPaths array:

{
  "skillPaths": [
    ".config/kimchi/harness/skills",
    ".claude/skills",
    "/absolute/path/to/shared-team-skills"
  ]
}

Skill File Format

A skill is a directory containing a SKILL.md file. The file has two parts: YAML frontmatter (between --- delimiters) and a markdown body with the agent instructions.

---
name: my-skill
description: What this skill does and when to use it
---
# My Skill

Step-by-step instructions for the agent.

Frontmatter fields

Unknown frontmatter fields are ignored.

Name validation

Skill names must:

• Contain only lowercase letters (a-z), digits (0-9), and hyphens (-)
• Not start or end with a hyphen
• Not contain consecutive hyphens
• Be at most 64 characters

Body guidelines

The markdown body is the instruction set the agent follows. Write it like a concise runbook:

• Put the important information first. The agent reads the body when the skill activates — lead with the action, not the background.
• Be specific about steps. Use numbered lists for sequential actions. Include exact commands, file paths, or tool names.
• Keep it focused. One skill, one job. If a skill tries to do too many things, split it.
• Keep it short. Aim for under 5,000 tokens. Long instructions dilute the signal and use context window budget.

Directory structure

my-skill/
├── SKILL.md            # required — frontmatter + instructions
├── scripts/            # optional — helper scripts
├── references/         # optional — detailed docs, loaded on-demand
└── assets/             # optional — templates, data files

The only required file is SKILL.md. Everything else is freeform — organize supporting files however makes sense for the skill. Use relative paths in the skill body to reference them.

Example

---
name: lint-fix
description: Run the project linter and auto-fix all fixable issues
---
# Lint Fix

Run the project's linter with auto-fix enabled.

## Steps

1. Detect the project type (check for `package.json`, `Cargo.toml`, `pyproject.toml`).
2. Run the appropriate lint command with auto-fix:
   - Node.js: `npx eslint . --fix` or `npx biome check --write`
   - Rust: `cargo clippy --fix --allow-dirty`
   - Python: `ruff check --fix .`
3. Report what changed.

Invoking Skills

Skills activate in two ways:

• Slash commands — Type /<skill-name> in the prompt to invoke a skill directly. You can pass arguments after the command (e.g., /lint-fix src/). Skills with disable-model-invocation: true in their frontmatter can only be invoked this way.
• Automatic activation — At startup, Kimchi scans skill directories and adds each skill's name and description to the agent's system prompt. When your request matches a skill's description, the agent loads the full SKILL.md on demand and follows its instructions. Only the descriptions stay in context — full skill instructions are loaded when needed, keeping the prompt compact.

Installing Skills

From a Git repository

Clone a skill repository directly into a scanned directory:

git clone https://github.com/user/my-skill.git ~/.config/kimchi/harness/skills/my-skill

Manual installation

Copy a skill directory into a scanned skill path:

cp -r my-skill ~/.config/kimchi/harness/skills/my-skill

Creating Custom Skills

Manually

Via the agent

During a session, ask the agent to create a skill and it will:

• Validate the name against the naming rules
• Validate the frontmatter format
• Write the SKILL.md file to the skills directory

Sharing skills with your team

To share skills across a team, place them in a shared directory and add it as a custom skill location during kimchi setup. You can also commit skills to a repository directory and have team members add that path during their own setup.

Managing Skills

Use the /improve command during a session to review and consolidate your skills. The agent can identify overlapping skills and suggest merging them.

To remove a skill, delete its directory from the skills folder. If a skill is removed through the agent, it is moved to a .archive/ subdirectory rather than permanently deleted — you can recover it by moving it back.

Troubleshooting

Project Rules

Kimchi reads project context files to understand your repository's conventions, constraints, and guidelines. These files are injected into the agent's system prompt at the start of every session — they apply to every task, not just specific triggers.

Supported files

Kimchi looks for these files in each directory from the filesystem root down to your current working directory:

Per directory, AGENTS.md is checked first. If found, CLAUDE.md is skipped for that directory. This means you can use whichever convention your team prefers — or use AGENTS.md if you want rules that apply across multiple AI coding tools.

Local overrides

Each context file has a .local.md variant for user-specific, gitignored overrides:

• AGENTS.local.md — appended to AGENTS.md
• CLAUDE.local.md — appended to CLAUDE.md

A .local.md file without a corresponding primary file is also loaded on its own. Add .local.md files to your .gitignore to keep personal preferences out of the shared repository.

Resolution order

Files are loaded ancestor-first — the root directory's rules are applied first, and the current working directory's rules are applied last. This means project-root rules provide the baseline, and subdirectory rules can refine or override them.

/                         ← checked first
├── CLAUDE.md             ← loaded (root-level rules)
├── projects/
│   └── my-app/
│       ├── AGENTS.md     ← loaded (project-level rules)
│       ├── AGENTS.local.md  ← appended (local overrides)
│       └── src/
│           └── ...       ← cwd: rules from / and /projects/my-app/ both apply

What to put in project rules

Use these files for standing instructions that apply to every session:

• Coding conventions (naming, formatting, test patterns)
• Architecture constraints (e.g., "do not add new dependencies without approval")
• Repository-specific context (e.g., "this is a monorepo; packages are in /packages")
• Review preferences (e.g., "always run make lint before committing")
• Technology choices (e.g., "use Vitest, not Jest" or "prefer fetch over axios")

Cursor Rules

Kimchi supports Cursor-style project rules — .mdc files with YAML frontmatter that control when and how rules are injected into the agent's system prompt. This lets teams that already maintain Cursor rules reuse them in Kimchi without duplication.

The extensions.cursor-rules extension is enabled by default. To disable it:

kimchi resources disable extensions.cursor-rules

Supported file locations

Kimchi discovers Cursor rules from two directory conventions and a legacy format:

Kimchi walks from the current working directory up to the filesystem root, collecting rules at every ancestor level. Rules are ordered ancestor-first (root → cwd), so higher-level rules provide the baseline and closer rules refine them. Files are deduplicated by absolute path.

Subdirectories within .cursor/rules/ and .agents/rules/ are scanned recursively — you can organize rules into folders.

.mdc file format

An .mdc file contains optional YAML frontmatter (between --- delimiters) followed by a markdown body:

---
description: TypeScript conventions
globs:
  - "src/**/*.ts"
  - "src/**/*.tsx"
alwaysApply: true
---

# TypeScript

Use strict mode. Prefer unknown over any.

Frontmatter fields

Globs can be specified as a YAML list or as a comma-separated string (e.g., "*.ts, *.tsx"). Glob patterns are resolved relative to the directory containing the .cursor/ or .agents/ folder.

Activation modes

Rules activate in one of three ways depending on their frontmatter:

When a rule has alwaysApply: true, it takes priority regardless of whether globs or description are also present.

Legacy .cursorrules

A .cursorrules file at any ancestor directory is treated as a single always-apply rule. The entire file content is injected into the system prompt. No frontmatter parsing is performed.