# Machine Profile

> Re-runnable profile of this machine's facts and identity domains, with drift between the stored profile and the host now; read-only unless the operator confirms a write, never installs, never reapplies a stored value on its own. Use when: 'profile this machine', 'what does this host have configured', 'has this machine changed', 'which identity domains exist here', 'hand my machine facts to setup'.

- Skill: `melodic-software/machine-profile` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add melodic-software/machine-profile`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/machine-profile/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: melodic-software (https://skillmd.com/u/melodic-software)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/melodic-software/machine-profile

---


## Purpose

Record, once per machine, what the host has and which identity domains it holds, with the observation behind every value, so a plugin `setup` run starts from observed answers and a kept default says whether anyone looked. The profile drives setups; it never replaces their prerequisite logic. Design and rulings: [machine-profile-design](https://github.com/melodic-software/claude-code-plugins/blob/038c2ae22c23f60500b339fd2f66e4569ecbe2fd/docs/specs/machine-profile-design.md), placement in ADR 0041.

Everything here is read-only except two steps the operator confirms in that turn: `record --confirm` (writes the profile document) and `apply --confirm` (prints what to hand to each setup; it writes nothing itself).

## Actions

`<script>` is `bash "${CLAUDE_SKILL_DIR}/scripts/profile.sh"`. Every command that reads or writes the store takes `--data-dir "${CLAUDE_PLUGIN_DATA}"`.

- **profile** (default). Run `/harness-ops:prerequisites`, save its table to a scratch file, then run `<script> discover --prerequisites <file>` and print what it observed: machine facts, then each identity domain with its tree, git include, `gh` directory and verdicts. Offer to record it. On the operator's yes, run `<script> record --data-dir ... --confirm <saved discover output>`; without `--confirm` it validates and writes nothing.
- **diff**. `<script> diff --data-dir ... --prerequisites <file>` compares the stored document with fresh discovery. Empty output and exit 0 mean nothing changed: say so and ask nothing. Exit 4 lists each difference with both values and both `observed_by` entries. The store cannot tell a hand edit from a host change, so report the difference and do not attribute it.
- **explain** `<key>`. `<script> explain --data-dir ... <key>` prints the stored record and the command or path behind it.
- **apply** `--option <key>`. Run `diff` first and show it. Then `<script> apply --data-dir ... --option <key>` prints the plan. Only after the operator says yes in that turn, add `--confirm`. Setup skills are `disable-model-invocation: true`, so a `handoff` line is relayed for the operator to type as `/<plugin>:setup`; the model does not invoke it. An option recorded under a domain is a per-domain identity: the script reports a `conflict` and stops for it, and it is never put into the single `pluginConfigs` slot.

Exit codes: 0 ok, 1 refused, 2 usage or missing tool (`jq`), 3 no profile stored, 4 differences found.

## Where the profile lives

`${CLAUDE_PLUGIN_DATA}/machine-profile/profile.json`. The machine section is not project-keyed (it describes the host, the same for every project), which the design ratifies as a deviation from `docs/contracts/plugin-data-report-keying` rule 1; each domain is keyed by its tree root. A missing document reads as "no profile for this machine" and offers to produce one; there is no fallback path. The document is regenerable from the host, so uninstalling the plugin from its last scope costs a re-run, not data. It holds names, paths and observation commands, and discovery never reads a credential or a sensitive `userConfig` value. The writer is a backstop for hand-supplied records, not a secret detector: it refuses the key words and value shapes listed under Gotchas, so do not supply a secret that matches neither.

We keep the profile in the plugin data directory, accepting that an uninstall from the last scope can remove it.

- **Pointer**: when stating where `${CLAUDE_PLUGIN_DATA}` resolves or when uninstall removes it, fetch [plugin manifest reference: environment variables](https://code.claude.com/docs/en/plugins/manifest-reference#environment-variables) and [plugin uninstall](https://code.claude.com/docs/en/plugins/cli-reference#plugin-uninstall) live. **As of**: 2026-10-11. **Recheck trigger**: the plugins reference changes the data directory location or its uninstall behavior.

## Document shape and verdicts

Records live in `machine.facts`, `machine.options`, and per domain in `identity`, `facts` and `options`. Each record has `key`, `value`, `verdict`, and these by verdict:

| Verdict | Meaning | Required |
|---|---|---|
| `set` | a non-default value is in force | `observed_by`, `mode`, `supplied_by` |
| `default-verified` | unset; discovery looked | `observed_by`, `mode`, `observation` (including "found nothing") |
| `default-unexamined` | unset; nothing was looked at | `skipped_because`, and no `observed_by` |
| `blocked` | a guard prevents the change | `observed_by`, `mode`, `guard` with the operator command |

`mode` is `observed` or `reproduced`. A binary whose row in the prerequisites table names a `:setup check` is `reproduced`, because that setup is hidden and the profile cannot run its own check. A fact discovery measured directly (a binary present, a path, a core count) is recorded `set` with the source in `supplied_by`; absence is `default-verified`. There is no bare `keep`, and a value equal to its default is never written to mark it decided. `default-unexamined` becomes `default-verified` only through an observation, never through written rationale.

Discovery reads identity domains from the `includeIf "gitdir:..."` entries in `git config --list --show-origin`. It attaches a `gh` directory to a tree only when that tree's own `.envrc` exports a literal `GH_CONFIG_DIR`, which it reads as text and never evaluates; otherwise `gh_config_dir` is `default-unexamined` and the machine's directory is not copied to the tree.

We attach a `gh` directory to a tree only through a literal `GH_CONFIG_DIR` in its `.envrc`, because we read `gh`'s lookup as naming no directory per working directory. **Pointer:** when stating where `gh` finds its configuration directory, read [gh help environment](https://cli.github.com/manual/gh_help_environment) live. **As of:** 2026-11-10. **Recheck:** that page changes the `GH_CONFIG_DIR` lookup order.

We treat one `pluginConfigs` slot as serving the whole machine. **Pointer:** when stating which scopes `pluginConfigs` is read from, fetch [settings reference: pluginConfigs](https://code.claude.com/docs/en/settings-reference#pluginconfigs) live; for what `claude plugin install --config` writes, read facts 5 and 9 of `docs/contracts/hook-config-delivery` (probes on Claude Code 2.1.292, 2026-10-07, and 2.1.283, 2026-09-27). **As of:** 2026-11-10. **Recheck:** the settings guide stops letting `--settings` set user-scope keys, the documented `pluginConfigs` scope changes, or `--config` starts honoring a scope flag.

## Next

- A binary row is missing: /harness-ops:prerequisites
- The fleet's plugin versions, a different question: /harness-ops:plugins-audit

## Gotchas

Binary facts come only from the prerequisites table. Without `--prerequisites`, discovery records `binaries` as `default-unexamined` and adds no probe of its own, so a `diff` run without the table reports the per-tool rows as removed.

The writer refuses a record whose key contains `token`, `secret`, `password`, `credential`, `api_key` or `private_key`, and a record whose value looks like a credential: a GitHub, AWS, Slack or `sk-` token, a JWT, a private-key block, or a URL with an embedded password. A key discovery derives from host text (a binary such as `docker-credential-pass`, an include path under a `token` directory) gets the first letter of each such word bracketed, as `binary.docker-[c]redential-pass`, so the profile still records it. `explain` needs the bracketed key, and a hand-supplied record keyed `api_token` is still refused.

`diff` compares facts and identity only. Option records are stored state that discovery does not observe, so a hand-edited or never-applied option does not show as drift.

`record` replaces the whole document, so options recorded earlier survive a re-record only when they are merged into the document first.

Discovery reads the effective user and system git configuration from a neutral directory, so the repository the session runs in does not add or hide a domain.

A read-only include file is detected with `test -w`; an immutable attribute on a file that still looks writable is not.

Do not reapply a stored value from a hook, a session start or a schedule. `apply` re-asserts a value only when the operator selects it in that run.

