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. 11 exist today. They range from a session opener that loads project context, to a help-documentation builder that regenerates an application’s help with annotated screenshots, to a monday.com sync and a publishing pipeline that carries a project from branch setup through production promotion, requirements-traceability review, and the team’s internal documentation platform.
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 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 instead of being retold.
The mistake that taught the most cost months of a tool silently not working. The assistant treats a command and a skill as different things: a command runs only when a person types its name, and a skill is applied on the assistant’s own judgment when a task matches. My text-editing tool never functioned as a skill because the setup script only ever installed commands. There was no error; configuration in that location is inert. I then made a variant of the same mistake while fixing it, editing a name field when the command name comes from the filename, always.
That led to a real governance question, since three of the tools commit code, deploy applications, or rewrite files in bulk, and making those model-invocable hands the assistant the ability to deploy on its own judgment. A documented safety-tier convention now governs the library: only two of the 11, the session opener and the text editor, fire unprompted, and everything with side effects waits for an explicit request, stated in each skill’s own description. A plain-language catalog of all 11, split into what runs automatically and what runs on request, is published on the team’s internal documentation platform.
Actively maintained and growing: the library more than doubled in its second half, and its publishing cluster is what made the documentation platform possible. The convention that matters most is that new tools are verified after install, never assumed working, since the failure mode here is silence rather than error.
The technical detail
This repository holds the shared working instructions the team’s AI coding assistant runs under, put on each machine by a setup script and synchronized through ordinary version control. A documented, version-controlled set of shared instructions is a different kind of artifact from personal habits, however good: it can be reviewed, diffed, and pointed at.
The original five cover the session cycle, opening with context loaded and closing with a record committed, plus an in-app help builder, a whole-application layout auditor, and a text editor that strips the patterns making prose read as machine-generated. The six added later form two clusters, described in their own section below: a pair that keeps a project’s task list synchronized with a monday.com board, and a publishing pipeline that walks a project from a fresh branch to production promotion, requirements review, and documentation publishing. The full catalog, with what each tool has delivered, is in the table further down.
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, 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 had only ever installed the command form. Nothing errored, nothing warned, nothing diagnosed it, because configuration in that location is inert.
For that tool the distinction was the whole point. An instruction to avoid writing like a machine is worthless if someone must 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, while fixing it, I made the same mistake in a new form. 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 lets it deploy whenever its own judgment says so.
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 two of the 11 are intended to fire unprompted: the session opener, which reads, pulls, and loads context while changing nothing, and the text editor, which touches only the words in front of it. That line has since hardened into a documented tier convention across the whole library. Everything that commits, deploys, or edits in bulk waits for an explicit request, and each skill’s own description says so, which means the governance is carried by the artifact itself instead of by anyone’s memory of it.
The second wave: visibility and publishing
The library more than doubled in one later burst, and the six new tools split into two clusters with one shared motive: making the team’s work visible to people who do not read repositories.
The first cluster connects a project’s task list to a monday.com board. The design rule is that the board is never the source of truth. Each project keeps a backlog file in its own repository, that file is authoritative, and the board mirrors it, so if the two ever disagree the file wins on the next sync. What the board adds is timing. Status used to change when someone remembered to update it at the end of a session; it now flips the moment the real event happens. Work starting on a task moves it to In Progress, publishing to the development environment moves it to In Testing, and release to the live environment marks it Done with the date recorded. Every item’s name carries a short reference code, so a call or a chat can say “task 2.F” and everyone finds the same item without describing it by title.
One convention keeps the automation out of the humans’ way. When status changes, a short plain-language note is posted to the item’s update feed, never a raw commit identifier, and the board’s own Notes field is reserved for a person to write by hand, untouched by automation. Two board templates exist and are deliberately not unified: a phase-based one for larger builds, and an open-ended intake one for ongoing request streams. The Residential Client Portal and the Job Scheduler run the intake form with the automatic sync.
Setup and ongoing sync are two separate tools on purpose. Setup is a one-time bootstrap that finds or creates the board, migrates the project’s task list into the standard format, and records the connection. Sync is the ongoing connector: a read-only pull at session start, pushes at the trigger points above and at session end, with nobody needing to remember either.
The second cluster is a publishing pipeline: branch setup, production promotion, a full requirements-traceability review, and documentation publishing. The review tool is the one that produced the 64-row and 168-row reviews described on the Job Scheduler and Residential Client Portal pages, and the publishing tool is what feeds the documentation platform, where the reviews and the architecture documents now live.
The 11, in plain language
The same catalog published for the team, with what each one has delivered, because a list of tools without their value is just an inventory.
Runs automatically:
| Skill | What it does | What it has delivered |
|---|---|---|
| Session start | Pulls the latest shared skills and project code, loads project memory | Every session begins already knowing the project’s history; nothing is re-explained |
| Text editor | Strips the patterns that make prose read as machine-generated | Applies whenever writing happens, which is the entire point of it being a skill |
Runs on request:
| Skill | What it does | What it has delivered |
|---|---|---|
| Session done | Records what happened, syncs memory, commits | The worklogs every case study on this site was assembled from |
| Branch setup | Bootstraps a project’s branching and workflow conventions | New work starts the same way on every project |
| Help builder | Regenerates an application’s in-app help, annotated screenshots included | A 28-section, 30-screenshot help system that no longer decays when the interface changes |
| Layout auditor | Checks every page for alignment and layout problems and fixes findings | A whole-application visual pass as a single request |
| monday.com setup | One-time board bootstrap: find or create, migrate the task list, record the connection | Two projects connected so far |
| monday.com sync | Keeps board status flipping in real time as work starts, publishes, releases | Stakeholders watch progress without asking for it |
| Production promotion | Carries a change through the three-tier deployment gate | The gate gets followed, every time, including when it feels unnecessary |
| Requirements review | Builds a full requirements-traceability matrix from the code | The 168-row and 64-row reviews, findings recorded with file, line, and verification step |
| Documentation publishing | Renders and publishes documents to the internal platform | More than 30 documents with URLs colleagues open |
How the help documentation tool works
Of the five tools, this one does the most work, and 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 instead of 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 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
- Pattern matching cannot be trusted to find a string inside a compiled binary. Confirming a deployed fix by reading the binary for a known string is sound, but a regular expression run against binary encoding returns false negatives even while the string sits right there. Three good deployments in a row were declared failures this way, and each verdict bought a debugging round for a problem that did not exist. A direct substring search works.
- Take the application offline with a marker file before publishing. While the application runs, the web server keeps its binary locked, so a publish over the live copy fails after retrying repeatedly. One mid-session rebuild and publish failed silently this way, and the previous version stayed on disk while the process looked 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 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, not a courtesy.
Timeline and effort
Work spans roughly 12 weeks. The worklog records 6 sessions, and the worklog is also the record that fell behind: roughly 20 commits of real activity landed after its last entry, including both new clusters. For a repository whose purpose is keeping a team’s records straight, that is its own small finding, and it is reported here instead of smoothed over.
Where it stands now
11 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 instead of a record of regret.
The convention that matters most is verifying after install, never assuming, since this project’s defining lesson is that a correct-looking configuration in the wrong location produces no error at all.