| name | file-ownership-boundaries |
| version | 1.0.0 |
| category | devops |
| description | Know which files are yours to modify vs Hermes defaults. Covers the two-domain split (Hermes Agent vs hermes-cortex repo), what each domain owns, and how to check before editing. |
| author | Hermes Cortex |
| platforms | ["linux","macos"] |
| metadata | {"hermes":{"tags":["ownership","boundaries","repo","hermes","architecture","domain"],"related_skills":["survey-before-action","agent-fundamentals","repo-organization","cortex-preflight"]}} |
File Ownership Boundaries
Why This Exists
This system has two domains with different ownership:
| Domain | Location | Who owns it | Can we modify? |
|---|
| Hermes Agent | ~/.hermes/ (core files) | Hermes Agent / Nous Research | No — gets overwritten on updates |
| Our repo | ~/hermes-cortex/ | Us | Yes — this is our codebase |
| Deployed runtime | ~/.hermes-cortex/ | Us (deployed from repo) | Edit repo source, then deploy |
| State/config | ~/.hermes-cortex/state/*, ~/.hermes/config.yaml | Per-machine | Yes — direct modification OK |
The Core Rule
Only create and modify files that have a source in our repo (~/hermes-cortex/).
If a file only exists in ~/.hermes/ and not in the repo: do not touch it.
Before Every File Edit
Ask yourself these three questions IN ORDER:
-
Is this file in ~/hermes-cortex/?
→ Yes: ✅ Edit freely. It's ours.
-
Is it ONLY in ~/.hermes/ and NOT in the repo?
→ Yes: ❌ STOP. It's a Hermes default. Do not touch it.
-
Is it somewhere else (deployed runtime, state file)?
→ Deployed runtime (~/.hermes-cortex/scripts/): find the repo source, edit there, then deploy
→ State/config: modify directly
Identifying Our Skills vs Hermes Defaults
Skills in ~/.hermes/skills/ come from two places. Know which is which:
| Origin | Path check | Action |
|---|
| Hermes Cortex (ours) | In ~/hermes-cortex/skills/ | ✅ Edit the repo source, deploy via cortex-update.sh |
| Hermes Agent (upstream) | In ~/.hermes/hermes-agent/skills/ but NOT in repo | ❌ Do not edit — create a supplement instead |
Hermes Agent upstream skills (do NOT edit): Any skill at ~/.hermes/hermes-agent/skills/ that does NOT have a matching source in ~/hermes-cortex/skills/. This includes all skills in apple/, creative/, email/, github/, media/, note-taking/, productivity/, research/, smart-home/, social-media/, software-development/spike, and others shipped by upstream.
Our skills (edit freely): All skills under ~/hermes-cortex/skills/<category>/<name>/, including those that share names with Hermes defaults (we customized them — root-cause-debugging, survey-before-action). Skills with author: Hermes Cortex in frontmatter are ours.
Name collisions: The only Hermes upstream skill that shares a name with ours is root-cause-debugging — our v2.0.0 is customized (6-phase vs upstream's 4-phase), being renamed to root-cause-debugging.
Our skills (edit freely):
- Anything in
~/hermes-cortex/skills/<category>/<name>/
- Anything in
~/hermes-cortex/ops/scripts/
- Any skill WHERE
skill_manage(action='create') was called (agent-created)
- Skills with `author: Hermes Cortex in frontmatter
The Deployed Copy Trap
Files at ~/.hermes-cortex/scripts/ and ~/.hermes-cortex/skills/ are deployed copies from the repo. If you edit them directly:
- Your changes will be lost on the next
cortex-update.sh
- Other agents won't get your improvements
Always edit the repo source first, then run cortex-update.sh to sync.
Exception: ~/.hermes-cortex/state/* files are per-machine state, not deployed from repo.
What To Do Instead of Editing a Hermes Default
If you need a capability that a Hermes default skill provides but it's missing something:
- Don't edit the Hermes default — it will be overwritten
- Create a complement in our repo — a new skill at
~/hermes-cortex/skills/<category>/<name>/
- Reference the Hermes default in your new skill's
related_skills field
- Deploy via cortex-update.sh so the fleet gets it
Pitfalls
- ❌ Editing a skill that's only at
~/.hermes/hermes-agent/skills/ (e.g. software-development/spike) — we don't own it, upstream overwrites
- ❌ Patching
~/.hermes-cortex/scripts/ files — next deploy overwrites your edits
- ❌ Creating a new file in
~/.hermes/skills/ — fleet can't get it; put it in the repo
- ✅ Creating
task-persistence skill in our repo — correct: all agents get it, Hermes doesn't overwrite
- ❌ Creating a new file when an existing one can be extended. Search 3+ different terms before concluding nothing exists. The most expensive mistake is building a parallel system because a single search missed the existing one.
The Sharing Filter
When the skill lifecycle or learnings pipeline evaluates something for upstreaming, apply this filter in order:
-
Is it a Hermes Agent upstream skill? (at ~/.hermes/hermes-agent/skills/ but NOT in ~/hermes-cortex/skills/)
→ ❌ Skip. The framework owns these — not ours to share.
-
Is it already in hermes-cortex repo with no substantive change?
→ ❌ Skip. Already shared with the fleet.
-
Is it a genuinely new or substantively improved hermes-cortex skill?
→ ✅ Share.
The test: "Would someone running Hermes Cortex benefit from this? Or is it already available through either the Hermes or hermes-cortex repos?"
Examples of what NOT to share:
- ❌ A patch to a Hermes default skill (already in Hermes repo)
- ❌ A one-line doc fix in an existing hermes-cortex skill (already shared)
- ❌ A session-specific workaround or one-off fix (ephemeral)
- ✅ A new hermes-cortex skill with reusable steps + pitfalls
- ✅ A substantive new phase in an existing our-skill (e.g. a new Phase in
change-checklist)
- ✅ A reference document under an existing our-skill umbrella
Quick Reference Card
| You want to... | Right action |
|---|
| Change a skill behavior | Check if it's ours → if Hermes default, create a new skill in repo |
| Add a workflow step | Create or update an agent-created skill |
| Fix a deployed script | Find the repo source at ~/hermes-cortex/ops/scripts/, edit there, deploy |
| Update a config file | Direct edit OK if it's state/config |
| Share with other agents | Put it in the repo under skills/ or ops/scripts/ |
| Extend a Hermes default | Create a supporting skill — see references/supporting-skill-pattern.md |
Related
- AGENTS.md item 23: Only modify files in our repo — never touch Hermes defaults
- AGENTS.md item 24: Sharing filter — only share new/substantive hermes-cortex changes
survey-before-action skill: Pre-flight checklist before file edits (Hermes Cortex, read-only)repo-organization skill: Repo structure and naming conventionspublic-contribution skill: Decision tree for sharing improvements (ours)change-checklist (devops): Pre-ship validation that includes file-ownership checks in Phase 0
