What is the best practice for sharing lots of documentation amongst many projects?
I’ve found I need to document everything we do which is custom. How to deploy. How to get secrets. How to use grpc and our protobufs module. Etc. But. We have 80+ projects and this is useful to all of them. What is the best way to share it?
Some shared git repo and submodule (ick)
Some shared git repo elsewhere on disk and soft links
Some install process like commands? But these aren’t commands.
This feature is still in Alpha. For now, you should place your context under ‘Skills’—you can find this in the 'Cursor Setting, Rules and Command, ’ section.
While Cursor only has this in their Nightly release, CLI tools like OpenCode or Claude Code already use it.
Think of a ‘Skill’ as a knowledge base. For example, if you add a ‘gRPC Skill’ with your docs, the AI will automatically pull from it whenever you’re working on gRPC tasks.
I second the adoption of skills. We have had really good results from agent skills, but they depend on the engineers agent of choice. We rolled our own solution several months ago before Claude and Cursor had integrated them and found that a simple markdown table of links to skill files was pretty helpful. different agents follow their markdown docs in different ways, and some (copilot) might not read the skills as often as they should. but in general this helps a lot.
I’d like to challenge the claim that you have to document everything. I know this is probably hyperbole, what makes you think you need to document something? Have you thought about how the practices of your business might be making it harder for your agent to operate?
*Side note: I’ve been itching to explore protobuf because it allows a single source of truth - something that drastically helps how the agent behaves within your codebase*
There is one problem I ran into - terminology. We are using one term differently than everyone else in the world, and that is just swimming upstream with agents. So we will have to fix that.
But mostly yes, we have to document everything. Writing software is about making decisions, and we have made thousands of decisions, and the agent doesn’t know about any of them and is unable to operate effectively. For instance they keep writing deployment plans for kubernetes - but we don’t use kubernetes. So this needs to be documented.
Humans can get away without documenting everything, because people join the company learn how things work, best practices, etc, and remember. Agents don’t remember. So we need documentation they can read.
Anyway… I’m using skills and commands a lot right now. Thanks!
