install.sh: drop .skill-source marker in deployed skill dir

The skill directory at ~/.agents/skills/opencode-mempalace-bridge/ is a
real dir containing a single SKILL.md symlink back into this repo — the
'colocated skill' pattern. Sibling reconcilers (skillset's
deploy-skills.sh, cli_utils's agents-sync.zsh) already handle external
dirs correctly via their existing 'leave real dirs alone' policies, but
a machine-readable marker makes ownership explicit:

  # skill-source: mempalace-toolkit
  # repo: <absolute path>
  # url: ssh://git@gitea.jordbo.se:2222/joakimp/mempalace-toolkit.git

The marker is the convention for any external repo that wants to ship a
colocated skill. The name is generic (.skill-source, not
.managed-by-mempalace-toolkit) so a second colocated skill from a
different repo can reuse the same file name; the first line identifies
the owner.

--uninstall now also removes the marker (only if it still says
mempalace-toolkit) and the now-empty skill dir.

AGENTS.md + README.md describe the pattern and point at sibling docs in
cli_utils/AGENTS-SYNC.md and skillset/README.md that mirror the
convention.

AGENTS.md

@@ -74,6 +74,24 @@ For `mempalace-docs`, test on a small repo (e.g. this one) first:
 - The convos miner dedups on `source_file` path only (no mtime check). Staging filenames must be stable per session; deleting a staged JSONL forces a re-mine.
 - The docs miner dedups on `source_file` path + `mtime`. That's why staging uses `cp -p` (preserves mtime).
 
+## Colocated skill pattern
+
+This repo owns an agent skill (`SKILL.md`) that lives alongside the code it documents, rather than in a central skills repo like [`skillset`](https://gitea.jordbo.se/joakimp/skillset). The advantages: the skill moves in lockstep with the wrappers it explains, one `git clone` gets you the full producer-side setup, and retirement (when upstream gaps close) removes skill + code + docs in one commit.
+
+The convention for making this coexist cleanly with sibling tooling:
+
+1. **`install.sh` creates `~/.agents/skills/<name>/` as a real directory** containing a `SKILL.md` symlink back into this repo. It does **not** create a dir-symlink, because real dirs are the signal that sibling reconcilers (skillset's `deploy-skills.sh`, cli_utils's `agents-sync.zsh`) should leave the dir alone.
+2. **`install.sh` drops a `.skill-source` marker file** at the root of the skill dir:
+   ```
+   # skill-source: mempalace-toolkit
+   # repo: <absolute path>
+   # url: ssh://git@gitea.jordbo.se:2222/joakimp/mempalace-toolkit.git
+   ```
+   This is a breadcrumb for humans and future tooling — it answers "who owns this skill dir?" at a glance. `deploy-skills.sh` and `agents-sync.zsh` don't read it today (their existing logic already handles external dirs correctly) but may surface it in status reports later.
+3. **`install.sh --uninstall` removes the marker** (only if it still says `mempalace-toolkit`) and the now-empty skill dir.
+
+If you add a third colocated skill from a new repo, follow the same convention. The marker format is shared; only the repo name changes.
+
 ## History
 
 Split out from [`cli_utils`](https://gitea.jordbo.se/joakimp/cli_utils) on 2026-04-30. The wrappers originated there but the conceptual fit was weak (`cli_utils` is interactive shell tools; these are agent memory infrastructure). Some older diary entries and KG facts in the palace reference the original paths.

README.md

@@ -142,6 +142,8 @@ The skill is the *short-form checklist* for agents — when to use which wrapper
 
 The skill pairs with the consumer-side [`mempalace` skill](https://github.com/MemPalace/mempalace) — that one covers using the palace (search, diary, KG); this one covers feeding it.
 
+**Colocated skill pattern.** The skill lives here (not in [`skillset`](https://gitea.jordbo.se/joakimp/skillset)) because it moves in lockstep with the wrappers it documents. `install.sh` drops a `.skill-source` marker file in the deployed skill directory so sibling tooling (skillset's `deploy-skills.sh`, cli_utils's `agents-sync.zsh`) can tell the directory is externally owned. See [`AGENTS.md`](AGENTS.md) for the full convention and how to adopt it for future colocated skills.
+
 ---
 
 ## See also

install.sh

@@ -38,10 +38,13 @@ What install does:
   - Symlinks SKILL.md into ~/.agents/skills/opencode-mempalace-bridge/SKILL.md
     (auto-discovered by opencode; run agents-sync from cli_utils to also
     reach Claude Code and Kiro)
+  - Drops a .skill-source marker in the skill dir so sibling tooling
+    (deploy-skills.sh, agents-sync.zsh) knows the dir is externally owned
 
 What uninstall does:
   - Removes symlinks in ~/.local/bin/ that point into this repo
   - Removes the skill symlink if it points into this repo
+  - Removes the .skill-source marker and empty skill dir
 EOF
             exit 0 ;;
         *) echo "Unknown flag: $1" >&2; exit 2 ;;
@@ -98,6 +101,26 @@ install_bin() {
 install_skill() {
     note "Linking companion agent skill"
     mkdir -p "$SKILL_DEST_DIR"
+
+    # Drop a marker file so sibling tooling (deploy-skills.sh, agents-sync.zsh,
+    # and any future reconciler) can tell at a glance that this skill directory
+    # is owned by an external repo and shouldn't be clobbered. The convention
+    # is two lines: "# skill-source: <repo-name>" + "# url: <clone-url>".
+    # Any colocated skill from any repo can adopt the same convention.
+    local marker="$SKILL_DEST_DIR/.skill-source"
+    if [[ ! -e "$marker" ]]; then
+        cat > "$marker" <<EOF
+# skill-source: mempalace-toolkit
+# repo: $SCRIPT_DIR
+# url: ssh://git@gitea.jordbo.se:2222/joakimp/mempalace-toolkit.git
+# This skill directory is managed by an external repo's install.sh.
+# deploy-skills.sh (skillset) and agents-sync.zsh (cli_utils) leave
+# directories containing this marker alone. Do not move SKILL.md out
+# of this directory without also updating the owning repo.
+EOF
+        ok "Wrote $marker"
+    fi
+
     if [[ -e "$SKILL_DEST" || -L "$SKILL_DEST" ]]; then
         if link_if_into_repo "$SKILL_DEST"; then
             ok "Skill already linked"
@@ -174,6 +197,18 @@ do_uninstall() {
         ok "No skill symlink to remove"
     fi
 
+    # Remove the marker and the now-empty skill directory, but only if
+    # the marker was written by us and the directory has nothing else in it.
+    local marker="$SKILL_DEST_DIR/.skill-source"
+    if [[ -f "$marker" ]] && grep -q '^# skill-source: mempalace-toolkit$' "$marker" 2>/dev/null; then
+        rm "$marker"
+        ok "Removed $marker"
+    fi
+    if [[ -d "$SKILL_DEST_DIR" ]] && [[ -z "$(ls -A "$SKILL_DEST_DIR" 2>/dev/null)" ]]; then
+        rmdir "$SKILL_DEST_DIR"
+        ok "Removed empty $SKILL_DEST_DIR"
+    fi
+
     echo
     ok "Done."
 }