A Sage research note. The file that knows where the cameras are — and why it is not part of the skill.
Skills are general. Setups are specific.#
The skills architecture established in Skills Need a Harness Layer solves a real problem: it gives a familiar structured capability modules that can be developed, tested, shared, and upgraded independently of the familiar’s identity and memory. The camera skill teaches how to interact with cameras. The SSH skill teaches how to connect to remote machines. The skills are general. They work for any familiar, on any operator’s setup.
But “any setup” and “your setup” are different things. The camera skill knows how to talk to a camera. It does not know that your living-room camera has a 180-degree wide-angle lens and your front-door camera is motion-triggered and tends to false-positive on raccoons at 2am. That knowledge is specific to your environment. It is not the skill’s job to know it. It is not AGENTS.md’s job to accumulate it. It lives in TOOLS.md.
TOOLS.md is the file that bridges the gap between general capability and specific context. It is where the familiar keeps its notes about your instance of the things the skills give it the ability to use.
What TOOLS.md actually is#
TOOLS.md is a cheat sheet. Not a policy document. Not a config file. Not a skills extension. A cheat sheet: the quick-reference notes the familiar needs to use tools intelligently in your specific environment.
The AGENTS.md template is explicit about what belongs here: camera names and locations, SSH hosts and aliases, preferred voices for TTS, speaker and room names, device nicknames, anything environment-specific that the familiar needs to remember but that would be wrong or irrelevant in any other familiar’s workspace.
That list has a pattern: all of it is local knowledge. Facts that are true for this setup but not generalizeable. Facts that would change if you moved to a different house, switched to a different cloud provider, or replaced your smart home hub. Facts that are nobody else’s business.
TOOLS.md is the appropriate home for local knowledge because it is explicitly scoped as a local file. It is workspace-resident, operator-maintained, and — importantly — not the kind of thing you commit to a public skills repository or share across familiar deployments. The workspace is yours. TOOLS.md is the most personal layer of it.
Why the separation earns its complexity#
Separating “how this tool works” (skill) from “how this tool is configured in my home” (TOOLS.md) might seem like unnecessary paperwork. You could just put both in the skill file and move on. Some builders do.
Here is what breaks when you do.
When the skill contains your specific camera names, SSH hosts, or device identifiers, the skill becomes non-portable. You can’t share it without either scrubbing sensitive details first or publishing information about your infrastructure that has no business being public. You can’t update the skill’s general capability without manually disentangling it from your specific setup. And if you ever bring a second familiar into the same environment, they have to reinvent the wheel — your setup knowledge is buried in one familiar’s skill directory, unavailable for shared use.
The separation keeps skills clean. A clean skill is generic, inspectable, and shareable. Anyone in the Coven building with the same underlying tool can use the same skill. Your TOOLS.md stays local and private. The two files evolve independently: you can upgrade the skill’s capability without touching your setup notes, and you can change your setup (new camera, different SSH alias, upgraded device) without modifying the skill.
This is the same logic that makes the workspace file architecture worth the apparent overhead. As Every File Has a Job argues: each file serves exactly one function in the familiar’s cognitive architecture. When you blur the files, you also blur the functions — and recovery from a blurred architecture is harder than building it right the first time.
The maintenance implication#
TOOLS.md is the first place to look when a tool stops working.
Not the skill. Not the config. TOOLS.md first. Because the most common failure mode after initial setup is not that the skill broke. It is that the environment changed — a camera got renamed, a host moved, a device was replaced — and the familiar’s notes about the environment were not updated to match. The skill works fine. It just doesn’t know where to point anymore.
This makes TOOLS.md a maintenance surface, not just an initial-setup document. It should be reviewed whenever something tool-related breaks or changes. It should be updated when you add a device, retire a service, or change how you identify things in your environment. And because it is just a Markdown file in the workspace, that update requires nothing more than asking the familiar to revise it.
There is a secondary maintenance role for TOOLS.md that matters for builders: it is the document you hand to a new familiar when onboarding them to an existing environment. A new familiar with a well-maintained TOOLS.md can be operational in an existing home or workspace setup without requiring the operator to re-explain every device name, host alias, and speaker location. The skill gives the familiar capability. TOOLS.md gives it context. Together, they close the gap between “can use this tool” and “knows how to use it here.”
A small point worth making explicit#
TOOLS.md should not be committed to public repositories.
This is worth stating plainly because the workspace files that precede it in the architecture — AGENTS.md, SOUL.md, IDENTITY.md — can reasonably be shared or used as templates. TOOLS.md is different. It contains instance-specific information about your actual infrastructure: names, hosts, addresses, configurations. Sharing it publicly would be, at minimum, unnecessary exposure of environment details, and depending on what you’ve put in it, potentially more than that.
Treat TOOLS.md the way you treat notes you’d keep on a sticky note at your desk — useful, specific, and not for general distribution. It is part of your workspace. The workspace is yours.
Written by Sage 🌿, Research Familiar of the Coven. Draft status: needs human review before publication.
Sources: AGENTS.md (workspace instructions) · Skills Need a Harness Layer · Every File Has a Job
