Skills & conventions

ka deliberately speaks the ecosystem’s formats instead of inventing its own. Drop files where ka looks and they are picked up: no registration, no config.

AGENTS.md

Project instructions, read from the repository root down to your cwd (at most 4 layers), CLAUDE.md is accepted as a compatibility alias. This is where the project’s build commands, style rules, and “don’t touch” zones live.

ka init   # generate a starter AGENTS.md from a repo scan

SKILL.md skills

Skills are folders with a SKILL.md (name, description, body), discovered in:

• .ka/skills/ in the project
• .agents/skills/, .claude/skills/ (compat)
• your user config directory

ka lists each skill’s name and description in context and reads the body only on demand (progressive disclosure), so a library of skills costs almost nothing until used.

Invoking a skill explicitly

/skill:release-checker v0.2.11

/skill:<name> [args] runs one skill now instead of waiting for the model to pick it from the listing: the full SKILL.md body is injected into that turn’s system prompt, and the args land in the prompt. The scope is per-turn, like allowed-tools on a custom command; it never persists. Unknown and feature-disabled skills are refused up front, naming the skill or the toggle. In the TUI, Tab completes /sk onto the colon and the discovered names complete past it.

Installing skills and other customizations

ka skill install <git-url|path> installs a skill into your user skills directory (~/.config/ka/skills), from a git URL or a local folder with a SKILL.md; --force overwrites an installed skill of the same name. ka skill list and ka skill remove <name> manage what’s installed. The same lifecycle generalizes to every customization kind: ka install <skill|agent|command|rule> <git-url|path> (with ka install list [kind] and ka install remove <kind> <name>). There is no registry and no manifest format; installing is the trust act, and discovery still respects the project’s trust decision.

MEMORY.md

Durable notes the assistant keeps about the project: a project-level MEMORY.md plus a user-global ~/.config/ka/MEMORY.md. Edit them directly or via /memory in the TUI.

Custom slash commands

Any markdown file in .ka/commands/ (also .agents/, .claude/, ~/.config/ka/commands/) becomes a /name slash command. $ARGUMENTS is substituted with whatever follows the command:

---
description: Explain a failing test
argument-hint: <test-name>
allowed-tools: read, grep
model: ollama/qwen3.5:9b
---
Find the test named $ARGUMENTS in this repo, run it, and explain
the failure in terms of the code under test, not the test harness.

Invoked as /explain auth::test_login. Frontmatter beyond the description is optional: allowed-tools restricts that turn’s toolset, and model runs the turn on that selector once (the switch never persists).

Disabling all of it

--safe-mode ignores every convention file, skill, agent, command, hook, MCP server, and LSP: the troubleshooting floor.