| name | repo-skill |
| description | Convention for per-repo skill directories at ~/.kon/projects/<repo-name>/skills/<name>/SKILL.md. Each named subdirectory is one skill. Agents load all SKILL.md files as the first step before memory entries. |
Repo Skill
Owner: user (writes the files) + all agents (read them)
Consumers: every agent, via skills/memory-loading step 0
What it is
A directory of skill files you write for a specific repo. Unlike memory entries (which are key-value facts agents accumulate over sessions), repo skills are your words, loaded verbatim before any work begins.
Each skill is a named subdirectory with a SKILL.md entry point and optional sibling files. Use as many or as few skills as you want — start with one and split later.
Use repo skills to capture things that are always true about this codebase:
- Language, build system, test runner, style guide
- Maintainer and review expectations
- Architectural invariants agents must not violate
- Conventions that differ from defaults in
~/.kon/public/memory/
- Known footguns or constraints
Path
~/.kon/projects/<repo-name>/skills/
├── build/
│ └── SKILL.md ← build commands, flags, test runner
├── conventions/
│ ├── SKILL.md ← coding style, naming, patterns
│ └── examples.md ← optional sibling files within a skill
└── architecture/
└── SKILL.md ← component layout, invariants
Example: ~/.kon/projects/duckdb/skills/build/SKILL.md
Resolve paths:
python3 $KON_ROOT/hooks/_kon_paths.py project-skills-dir
python3 $KON_ROOT/hooks/_kon_paths.py project-skill-files
Format
Plain markdown. No frontmatter required. Write what you'd tell a new engineer on their first day.
Example skills/build/SKILL.md:
# DuckDB — build
**Language**: C++17. All new code must compile clean with `-Wall -Werror`.
**Build**: `make reldebug` — always prefix with `CMAKE_BUILD_PARALLEL_LEVEL=10`.
**Test runner**: `make test`. No mocking — use real DuckDB instances.
Example skills/conventions/SKILL.md:
# DuckDB — conventions
**Maintainer**: Mark. Prefers small incremental PRs; address every comment directly.
**Architectural invariants**:
- Never acquire new locks inside the WAL write path.
- All new catalog entries must go through `CatalogTransaction`.
Loading behavior
- All
skills/*/SKILL.md files are loaded, sorted by skill name
- Optional sibling files within a skill subdirectory (e.g.
examples.md) are not auto-loaded — reference them from SKILL.md if needed
- If
skills/ does not exist: skip silently — no error, no prompt
- Agents print
[repo-skill: loaded — build, conventions] or [repo-skill: not found] in ## Loaded memory entries
Creating a skill
SKILL_DIR=$(python3 $KON_ROOT/hooks/_kon_paths.py project-skills-dir)
mkdir -p "$SKILL_DIR/build"
$EDITOR "$SKILL_DIR/build/SKILL.md"
Changes take effect immediately on the next agent startup.
What it is NOT
- Not a replacement for memory entries (those accumulate incrementally from sessions)
- Not auto-generated by agents — only you write them
- Not a
.cursorrules or AGENTS.md inside the repo — lives outside the repo in ~/.kon/ so it never appears in git history
