The real problem with Notion
The typical team has documentation. The problem is that it is the wrong kind: well-formatted pages about architecture that have not been updated in eight months, and a Slack search that requires knowing what to look for.
New developers spend their first weeks discovering undocumented conventions by asking senior engineers. Senior engineers spend significant time answering the same questions in slightly different forms. This reference architecture describes how kx skills are designed to absorb that load.
Skills as version-controlled knowledge
kx supports SKILL.md files: plain markdown documents that extend the agent with project-specific context. The team commits skills alongside the codebase:
.kx/skills/
architecture.md # Service topology, ADR summaries
conventions.md # Code review standards, naming rules
deployment.md # Deploy process, env variables, rollback steps
on-call.md # Escalation paths, common incidentsBecause skills are in the repository, they go through the same review process as code. An outdated skill gets a PR to fix it. The audit trail is git log.
What new developers do differently
On day one, a new developer runs kx in the repository. The skills load automatically. When they ask “how do we handle database migrations?”, kx answers from the skills file, not from a hallucinated best practice.
When they ask something not in the skills, the answer gets added to the skills. The knowledge base grows with the team.
The target outcome
The onboarding win comes from two places: less time waiting for answers from senior engineers, and less time discovering conventions by reading diffs. The skills file becomes the first thing senior engineers update when a convention changes.