docs(skills): make storage source, ownership, mutability, and Curator scope one legible contract #110133

Summary

The skills system currently exposes several independent concepts through overlapping labels:

1. physical/effective location — profile-local, skills.create_dir, skills.external_dirs, trusted project, plugin;
2. distribution origin / updater — bundled, Hub/URL, external upstream, user-authored, agent-authored;
3. write policy — foreground skill_manage, background review, Curator lifecycle;
4. Curator opt-in state — the .usage.json created_by: agent marker;
5. scope — skill content may be shared while usage/ownership state remains profile-local.

The documentation describes pieces of this model, but not as one contract, and the CLI collapses several categories. An operator cannot reliably answer “which copy is active, who can modify it, and who will update it?” without reading the implementation.

This was encountered while configuring the same agent-authored library across seven profiles while preserving bundled/Hub update ownership. The reproductions below use a fresh synthetic HERMES_HOME against current main (5dea46d13deec9549bdc2ea703ae9201d733c28d); they do not depend on that real installation.

This is not another request for a global skill store. It is a documentation + observability request for the behavior Hermes already exposes.

Where the documentation and surfaces diverge

1. The opening mental model is already false for supported roots

The Skills page says that “All skills live in ~/.hermes/skills/ — the primary directory and source of truth”:

• skills.md L7-L13

The same page later documents create_dir, external_dirs, and trusted project roots, while profiles use their own HERMES_HOME. “All skills” and a single “source of truth” therefore do not describe the supported resolution model.

2. external_dirs are called both read-only and mutable

The shipped config example says:

External dirs are read-only

• cli-config.yaml.example L1055-L1062

The user guide says existing external skills are updated in place and that external dirs are not a write-protection boundary:

• skills.md L389-L395
• skills.md L399-L410

Current implementation has a third, contextual rule: external/project roots are read-only to autonomous lifecycle maintenance, while user-directed tool calls may still edit them:

• agent/skill_utils.py L613-L623
• tools/skill_manager_guards.py L164-L181

So “read-only” is not a property of the directory alone; it currently depends on the write origin. PR #108040 may change the foreground default, which makes it even more important for the docs and config example to state the same final contract.

3. create_dir is documented as fully integrated, but is not

The guide recommends create_dir for a shared “brain” / fleet-wide volume and says its skills appear in the prompt index, skills_list, skill_view, and slash commands:

• skills.md L415-L431

On current main, a clean repro produces:

skill_manage create : true
in prompt index     : true
skills_list names   : []
skill_view          : Skill 'create-dir-audit-demo' not found.

The implementation has a canonical get_all_skills_dirs() containing local → create_dir → external:

• agent/skill_utils.py L398-L406

but the list/view path rebuilds roots as project + local + external and omits create_dir:

• tools/skills_tool.py L170-L188

This specific functional bug is already tracked by #108157. I am including it here only because the current documentation presents the broken path as the recommended no-hacks solution for shared creation.

4. hermes skills list cannot reveal the effective storage/ownership model

The installed-skills command accepts only all | hub | builtin | local:

• hermes_cli/subcommands/skills.py L65-L73

and classifies every non-Hub, non-bundled skill as local, regardless of whether the winning file is in an external or project root:

• hermes_cli/skills_hub.py L763-L805

Synthetic current-main output with one local skill, one external skill, and one create_dir skill:

Installed Skills
Name                 Source  Trust
external-audit-demo  local   local
local-audit-demo     local   local

0 hub-installed, 0 builtin, 2 local

The external skill is labeled local; the create_dir skill is absent because of #108157. There is no path or update-owner field with which to disambiguate them.

5. “agent-created” is still used as an operator-facing synonym for Curator-managed

The Curator guide eventually explains the actual contract correctly:

created_by is a policy flag, not a provenance claim

• curator.md L262-L280

The implementation says the same and shows that curator adopt writes created_by: agent to a user-authored skill:

• tools/skill_usage.py L271-L278
• tools/skill_usage.py L302-L325

That policy sidecar always lives under the active profile's get_hermes_home()/skills/.usage.json, not beside a shared create_dir artifact:

• tools/skill_usage.py L45-L50

Yet the same guide section is titled “What agent-created means”, its sample status reports agent-created=..., and the real CLI still prints that counter:

• curator.md L193-L239
• hermes_cli/curator.py L110-L124

That forces users to learn that “agent-created” sometimes means authorship and sometimes means “autonomous Curator writes are allowed.” Existing issue #70712 covers the Desktop “learned” badge; this issue asks that the docs and CLI stop overloading the same concept too.

Why this matters

This ambiguity affects safe operations rather than wording alone:

• an external/upstream-owned skill can be mistaken for a local owned copy;
• a user can assume “read-only” protects foreground writes when it currently does not;
• a user can assume an adopted skill was authored by the agent;
• a recommended create_dir shared setup advertises skills the agent cannot subsequently load;
• across profiles, shared content and profile-local lifecycle metadata can be mistaken for one shared management state.

The practical workaround is duplicate profile-local copies plus manual reconciliation—the opposite of the “shared brain” mental model suggested by the guide.

Requested outcome

Please define one canonical skills contract and expose it consistently. A matrix in the Skills page would be sufficient documentation-wise, with rows for:

• profile-local / bundled copy;
• Hub-installed;
• skills.create_dir;
• skills.external_dirs;
• trusted project skills;
• plugin-provided skills.

Suggested columns:

• resolution precedence and effective path;
• distribution origin / update owner;
• foreground skill_manage mutability;
• background-review mutability;
• Curator lifecycle eligibility (adopt, stale/archive, pin);
• location/scope of .usage.json state;
• whether hermes update or Hub update may overwrite the copy;
• which discovery surfaces include the root.

For operator visibility, hermes skills list (including JSON output if added) should report separate concepts rather than one overloaded Source value—for example location_kind, origin/update_owner, and curator_managed—or at minimum show the resolved path and distinguish external, create_dir, and project from profile-local.

Acceptance criteria

• skills.md, curator.md, and cli-config.yaml.example describe the same external-dir mutability contract.
• The opening Skills mental model covers profile-local, create_dir, external, project, and plugin roots instead of saying all skills live in one directory.
• create_dir is either integrated across every documented discovery surface (tracked by skills.create_dir skills are advertised in the prompt but skill_view / skills_list / slash commands can't find them #108157) or the docs stop claiming that it is.
• hermes skills list lets an operator identify the winning copy's location/update ownership; external skills are not reported only as local.
• Curator output distinguishes authorship/provenance from the autonomous-management opt-in; an adopted skill is not described as agent-authored.
• Multi-profile docs state explicitly whether content, usage metadata, and Curator ownership are profile-local or shared.
• Contract tests cover every documented root across prompt index, skills_list, skill_view, slash commands, and write/lifecycle guards.

Related, not duplicate

• skills.create_dir skills are advertised in the prompt but skill_view / skills_list / slash commands can't find them #108157 — functional create_dir discovery bug.
• [Bug/Security]: external_dirs skills misclassified as "learned" (agent-owned) with absent write/patch permission guard #108032 / PR fix(skills): classify external_dirs as external and default-deny in-place writes #108040 — external provenance and foreground write policy, primarily API/Desktop and mutation guarding.
• bug(desktop): local skills are mislabeled as learned regardless of origin #70712 — Desktop “learned” badge conflates local/unclassified with learned.
• Feature: make global skills truly global across profiles #19451 and [Feature]: Global, self-improving skills have no first-class home — and protecting them forces a DRY violation #34782 — first-class global/shared skill storage design.

Those issues each address one behavior or UI. This issue is for the missing cross-cutting documentation and operator-facing contract that ties storage, provenance/update ownership, mutability, Curator management, and profile scope together.