Skip to main content

clientos-context

A Claude Code skill that populates a clientos client's 04-llm-context/*.md files from free-form notes — full CRUD, routed into the right file and section, not appended as one undifferentiated blob.

What it does​

Client OS keeps one context folder per client at {CLIENTS_ROOT}/{slug}/04-llm-context/ (default /Volumes/dev-ssd/clients), holding exactly 8 markdown files seeded by client clientos init <slug>: brief.md, current-state.md, timeline.md, promises.md, open-tasks.md, repo-map.md, decisions.md, handoff.md — each with a defined shape (see skills/clientos-context/SKILL.md).

Handed a raw note — a meeting recap, a status update, a new commitment, a decision, or a plain brain-dump about a client — the skill:

  • Resolves the client (and, for multi-site clients, the specific project) the note belongs to
  • Reads all 8 files in the target directory before editing, so edits merge with what's there
  • Splits a single note across multiple files if it spans more than one kind of fact
  • Edits in place — updates an existing promises.md/decisions.md row instead of duplicating it, moves a finished item out of open-tasks.md instead of just appending a line below it
  • Reports a short per-file summary of what changed, rather than re-printing the files

It became project-aware: a client with multiple sites (e.g. Dawna: handyman/, christmas-lights/, allied-security/) can hold context at two levels — client-level (the 8 root files) and per-project (04-llm-context/{project-slug}/, its own copy of the 8 files) — and the skill routes a site-specific note to that project's subfolder while a cross-site fact goes to the client root.

The skill also has a checkpoint-flush mode: on request ("checkpoint", "flush", "save progress") or automatically at session end for a bound session (CLIENTOS_AUTOSWEEP=1 + client clientos bind), it reconciles what a working conversation established into the same files, using identical routing rules.

Why it was created​

Consulting-client facts arrive as unstructured input — meeting recaps, status updates, new commitments, decisions, brain-dumps — and without this skill, a human (or an LLM working freehand) has to manually decide which of the 8 files a given fact belongs in, and whether it's a net-new fact or an update/removal of something already recorded. The skill's own frontmatter states the trigger directly:

"Use when the user wants to record, update, correct, or clear notes for a client's 04-llm-context/*.md files ... Triggers on phrasing like 'update the client notes', 'log this for <client>', 'add this promise', 'populate llm-context', or a raw brain-dump about a client with no other instruction." — skills/clientos-context/SKILL.md

The 8-file, per-client 04-llm-context shape the skill fills in isn't something the skill invented — it traces back to the original clientos CRM migration plan (.omc/plans/clientos-crm-migration.md), which recovered and ported the clientos Postgres schema including its llm_context_files table and seeded a demo client with "8 llm_context_files rows." The skill exists to keep that on-disk/DB structure populated correctly as real client facts accumulate, instead of leaving it to manual bookkeeping.

The skill's project-aware behavior and its checkpoint-flush / auto-sweep companion were both driven by a later working session, documented in docs/session-notes/2026-07-28-clientos-context-capture-and-bridge.md. That session set out to explore syncing data between the clientos CRM and a sibling repo, and branched into three pieces of work — onboarding a new multi-site client (Dawna) and making context project-aware, building live session capture (checkpoint flush + an opt-in SessionEnd auto-sweep hook via CLIENTOS_AUTOSWEEP=1 + client clientos bind), and verifying that a clientos→cates-works data bridge already existed elsewhere. Session capture is the automated counterpart to this skill: the skill handles ad-hoc/manual notes, while auto-sweep passively reconciles an entire session transcript into the same files at session end, using the same routing rules.

How it was built​

The skill is original to client-os — not a migration from anywhere — built and refined across roughly ten commits:

  1. 24a474f created it as a single SKILL.md describing the full-CRUD routing behavior.
  2. bc71dd3 added README.md, metadata.json, and agents/openai.yaml so the skill's folder matches the vercel-labs/agent-skills layout expected by skills add installs.
  3. 94f5ca4, 350c57a, 0c72a21 made it project-aware, documented checkpoint flush + session binding, and fixed a command-reference typo.
  4. 7a03971 added the SessionEnd auto-sweep hook.
  5. 09ff60e rolled out multi-channel distribution — a scoped npm package (@client-os/...), a co-prefixed Claude Code plugin, and a dedicated release-skills script kept separate from the CLI's own binary-release pipeline. At this point the package was still private: true — nothing was published yet.
  6. 2b60e56 fixed two npm-packaging-breaking "repo-root-escape" paths left in metadata.json, flipped the package to private: false, and added it to docs/published-skills.json — the commit that actually enabled publishing.

Two on-disk copies exist and are kept in sync, not duplicated by hand: skills/clientos-context/ is the canonical, authored copy; packages/skill-clientos-context/ is the same files (plus package.json and LICENSE) synced in by bin/sync-skill-content.mjs. Releases go through changesets, via the repo's dedicated release-skills script rather than the CLI's tag-driven binary-release pipeline.

How to install and use it today​

npm package​

npm install @client-os/skill-clientos-context

The package is public (packages/skill-clientos-context/package.json: "private": false, "publishConfig": {"access": "public"}) and listed in docs/published-skills.json, the allowlist of skill packages this repo actually publishes.

Claude Code plugin marketplace​

This repo itself is a Claude Code plugin marketplace source. Its manifest, .claude-plugin/marketplace.json, currently exposes one plugin — co — which bundles this skill:

{
  "name": "client-os",
  "owner": { "name": "Personal" },
  "plugins": [
    {
      "name": "co",
      "description": "1 skills, distributed via the co plugin command prefix.",
      "source": "./",
      "strict": false,
      "skills": ["./skills/clientos-context"]
    }
  ]
}

Add this repo as a plugin marketplace in Claude Code and install the co plugin to get the skill available as /co:clientos-context in your own sessions. This channel is independent of the npm package — it reads directly from the skills/ directory in the repo.

Using it​

Once installed, invoke it with natural language rather than a slash command for its primary use — drop in a note like "log this for <client>: promised the API docs by June 27" or a raw brain-dump with no other instruction, and the skill resolves the client, reads the existing 8 files, and edits the right ones in place. It reports back a short per-file summary of what changed. It does not push changes to the database automatically — run client clientos sync-files <slug> yourself when you want the edited files synced into the llm_context_files table.