What it is
This is a single repository holding the reusable instructions our team uses when working with an AI coding assistant, installed onto each person’s machine through a setup script and kept in sync through ordinary version control. Five exist today: one that opens a session by pulling the latest code and loading project context, one that closes a session by recording what happened and committing it, one that builds and maintains an application’s in-app help documentation end to end including screenshots, one that audits every page for layout and alignment problems and fixes what it finds, and one that edits written text to remove the patterns that make prose read as machine-generated.
Why it mattered
Before this existed, each person’s working habits with the assistant lived in their own head and their own local configuration. That produces inconsistent output across a team, and more importantly, it is not auditable. In a regulated environment, being able to show how AI-assisted work is actually governed is part of the job, and “everyone has their own approach” is not an answer that survives a security review.
Version control also means a lesson learned once propagates to everyone on the next pull, rather than being retold.
The distinction that caused the most trouble
The assistant treats two things as fundamentally different, and getting this wrong cost me months of a tool silently not working.
An instruction file placed in one directory becomes a command, invoked only when a person explicitly types its name. Placed in a different directory entirely, it becomes a skill, which the assistant chooses to apply on its own when a task matches its description. The configuration block declaring a name and description is required for the second form and completely ignored in the first.
My text-editing tool had a perfectly valid configuration block from the day it was written, and it never functioned as a skill, because the setup script only ever installed commands. There was no error. Configuration in that location is simply inert. For that particular tool the distinction was the entire point: an instruction to avoid writing like a machine is worthless if someone has to remember to ask for it.
I then made a variant of the same mistake while fixing it, editing the name field in the configuration to rename the command and reporting the rename as done. The command name comes from the filename, always. The configuration field only controls the skill’s directory name. Renaming requires moving the file.
The judgment call underneath it
Once both installation forms worked, a real question followed. Three of these five tools commit code, deploy applications, or rewrite files across an entire project. Making those model-invocable means the assistant decides when to run them, which effectively hands it the ability to deploy on its own judgment.
I kept both forms for all five, but added explicit wait-to-be-asked language to the descriptions of the three that carry side effects. Only the session-opening tool, which reads and pulls but changes nothing, is intended to fire unprompted.
The result
Five tools, installed in both forms, synchronized across the team through version control. A lessons file records each mistake and the rule it produced, which is read at the start of future sessions and is the actual mechanism that stops recurrence.
Where it stands
Actively maintained. The convention that matters most is the one requiring new tools to be verified after install rather than assumed working, since the failure mode here is silence rather than error.