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.
This commit is contained in:
Joakim Persson
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
+35
@@ -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."
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user