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 trigger (a slash command, a matching task, or a keyword), it follows that skill's instructions.

Skills differ from project rules. Skills activate on demand for specific tasks; project rules (AGENTS.md, CLAUDE.md) 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.

Cross-agent compatibility

Kimchi discovers skills from Claude Code (~/.claude/skills/, <project>/.claude/skills/) and Pi (~/.pi/agent/skills/) directories. If you already use skills with those tools, Kimchi picks them up automatically — no duplication needed.

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

Name validation

Skill names must:

• Start with a lowercase letter or digit
• Contain only lowercase letters, digits, dots (.), underscores (_), or 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
├── references/         # optional — specs, docs, API references
├── templates/          # optional — code or config scaffolds
├── scripts/            # optional — helper scripts the agent can run
└── assets/             # optional — images, diagrams, data files

Skills can include supporting files in these subdirectories alongside SKILL.md.

Example

---
name: lint-fix
description: Run the project linter and auto-fix all fixable issues
triggers:
  - user types "/lint-fix"
  - user asks to fix lint errors
category: workflow
---
# Lint Fix

When triggered, 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. Skills in the global harness directory (~/.config/kimchi/harness/skills/) that declare triggers with user types "/<name>" are available as slash commands.
• Automatic activation — The agent sees all loaded skill descriptions in its system prompt. When your request matches a skill's description, the agent follows its instructions without you typing a slash command. You can also ask the agent what skills are available.

Built-in Superpowers Skills

Kimchi ships with the obra/superpowers skill library — 14 methodology skills for structured workflows like test-driven development, debugging, code review, and planning.

On first launch, Kimchi downloads the pinned superpowers release to ~/.config/kimchi/vendor/superpowers/. The download is skipped if you're offline and retried on the next launch. If you already have superpowers installed manually in ~/.config/kimchi/harness/skills/, Kimchi skips the vendor path to avoid duplicates.

For the full list of included skills and version pinning details, see Built-in Superpowers Skills in the CLI reference.

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")