repo-skill

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   # → .../skills/
python3 $KON_ROOT/hooks/_kon_paths.py project-skill-files  # → all skills/*/SKILL.md, sorted

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