The real problem with Notion
The team had documentation. The problem was that the documentation was the wrong kind: well-formatted pages about architecture that had not been updated in eight months, and a Slack search that required knowing what to look for.
New developers spent their first two weeks discovering undocumented conventions by asking senior engineers. Senior engineers spent significant time answering the same questions in slightly different forms.
Skills as version-controlled knowledge
kx supports SKILL.md files — plain markdown documents that extend the agent with project-specific context. The team committed 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 incidents
Because 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 actually 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.
Result
The 4-to-2-week reduction came from two places: less time waiting for answers from senior engineers, and less time discovering conventions by reading diffs. The skills file became the first thing senior engineers update when a convention changes.