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 synchronized through ordinary version control.
Five exist today. One opens a session by pulling the latest shared instructions and project code and loading project memory. One closes a session by recording what happened and committing it. One builds and maintains an application’s in-app help documentation end to end, discovering pages, capturing annotated screenshots for every tab and revealed state, deploying, and committing. One audits every page in an application for alignment and layout problems, fixes every finding, verifies the build, and reports a summary. One 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 directory. That produces inconsistent output across a team, and more importantly it is not auditable.
In a regulated environment, being able to demonstrate how AI-assisted work is actually governed is part of the job. “Everyone has their own approach” does not survive a security review, and neither does a set of undocumented personal habits that happen to be good. A documented, version-controlled set of shared instructions is a different kind of artifact: it can be reviewed, diffed, and pointed at.
Version control also means a lesson learned once propagates to everyone on their next pull rather than being retold in conversation.
The distinction that cost months of silence
The assistant treats two things as fundamentally different, and getting it wrong meant one tool never worked at all.
| Slash command | Skill | |
|---|---|---|
| Installed to | commands directory | skills directory |
| Invoked by | The person, explicitly by name | The assistant, when the description matches the task |
| Needs configuration block | No, it is ignored | Yes, required |
An instruction file in the commands directory becomes something a person invokes by typing its name. The configuration block declaring a name and description is not read there. In the skills directory, the same file becomes something the assistant chooses to apply on its own, and the configuration block is required.
My text-editing tool had a complete, valid configuration block from the day it was written. It never functioned as a skill for months, because the setup script only ever installed commands. There was no error, no warning, and no diagnostic. 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 each time. As a command it was a tool nobody reached for; as a skill it applies whenever writing happens.
Then I made a variant of the same mistake while fixing it. Renaming all five tools to a consistent prefix, I edited the name field in each configuration block, confirmed it looked correct, and reported that the commands would now appear under the new names. They did not. The command name is the filename, always. The configuration field only ever controls the skill’s directory name. Renaming a command requires moving the file.
Two related errors, weeks apart, both from assuming that a field labeled “name” controls the name.
The judgment call about autonomy
Once both installation forms worked, a real question followed, and it is the one I would want a security reviewer to ask about.
Three of these five tools carry side effects. One commits code. One deploys an application and commits. One rewrites page files across an entire application. Making those model-invocable means the assistant decides when to run them, which effectively grants it the ability to deploy on its own judgment.
I kept both installation forms for all five, and added explicit wait-to-be-asked language to the descriptions of the three that carry side effects, so the assistant’s own instructions tell it not to fire those unprompted. The setup script also supports a commands-only flag for anyone who wants a stronger guarantee.
Only the session-opening tool is intended to fire unprompted, and that is deliberate: it reads, pulls, and loads context, and changes nothing. It is the one case where automatic invocation is purely beneficial, since the alternative is a session that begins without knowing the project’s history.
How the help documentation tool actually works
Of the five tools, this one does the most work, and it is worth describing because building help documentation by hand is a task that quietly consumes days and decays immediately after.
The tool runs end to end. It discovers the application’s pages by reading the routes, then drives a real browser to each page, captures a screenshot of every tab and every revealed state, such as a form that only appears after clicking add, and applies numbered callout annotations to the images. It then generates or updates the help page content to match, deploys, and commits.
The pieces that make it usable rather than a demo are the unglamorous ones: it handles multi-section help layouts rather than assuming a single page, since applications past a handful of pages need sectioned navigation; it follows documented conventions for help icons and navigation links so every application’s help looks and behaves the same way; and the single-page skeleton was explicitly demoted to guidance for applications of five pages or fewer after two larger applications showed it did not scale.
A verification lesson from the help documentation tool
The help documentation tool scans an application’s pages and generates or updates its in-app help. A subagent reports what controls and tabs currently exist on each page.
The gap: a summary of what currently exists says nothing about what used to exist and has since been removed. In one help update, a section still documented a card with a numbered callout, and that card had already been deleted from the page. The generated help was accurate about everything present and stale about something absent.
The fix was adding an explicit removal check as a required step: for each changed page, open the existing help content and verify that every documented row or sub-section still has a matching control in the current markup, dropping any that no longer match. The general principle, which applies well beyond this tool, is that a summary of current state cannot detect a deletion. Detecting removals requires comparing against the previous state deliberately.
Bugs and rules worth recording
- Never verify a string inside a compiled binary using pattern matching. Confirming a deployed fix by reading the binary and searching for a known string is correct; doing it with a regular expression is not, because binary encoding produces false negatives even when the string is present. Three successful deployments were each reported as failed for this reason, costing a full debugging round on a nonexistent problem. Direct substring search works.
- Stage an offline marker before publishing. The web server holds the application binary open while running, so publishing over a live application fails after repeated retries. A mid-session rebuild and publish silently failed for this reason, leaving the previous version on disk while the process appeared to complete.
- Consult the shared template before scaffolding any new repository. This repository’s own creation started without checking the conventions already established in the application template, and had to be stopped and redone. The structure conventions, memory folder layout, and guidance document format all already existed; starting fresh produced something inconsistent with every other project.
- Verify the install actually landed. Given that the entire failure mode in this project is silence rather than error, checking the installed symlinks after setup is a required step rather than a courtesy.
Timeline and effort
Work ran across roughly 6 weeks and 6 distinct working sessions. The repository was scaffolded and the first two tools written on the opening day, with the installation overhaul and prefix rename occurring near the end.
Where it stands now
Five tools, installed in both forms, synchronized across the team through version control. A lessons file records each mistake and the rule it produced, and that file is read at the start of future sessions, which is what makes it the mechanism that prevents recurrence rather than a record of regret.
The convention that matters most is verifying after install rather than assuming, since this project’s defining lesson is that a correct-looking configuration in the wrong location produces no error at all.