@thesmurph/agentlink 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- `agentlink init` creates `AGENTS.md` and `.agents/skills/`, adopts an existing
+  `CLAUDE.md` or `GEMINI.md`, folds stray real skill directories into the
+  canonical tree, and links every selected harness.
+- Symlinks are relative, so clones and git worktrees resolve at any path.
+- 17 harnesses, with a documentation source per row. Harnesses that already read
+  `AGENTS.md` or `.agents/skills/` are reported as native and left alone. Rows
+  with no documented path report as unknown instead of linking somewhere nothing
+  reads.
+- `sync`, `fix`, `select`, `list`, `doctor`, `adopt` and `unlink`, plus `--global`
+  for a home-directory setup.
+- An idempotent clause appended to `AGENTS.md` so future agents follow the
+  convention without a human explaining it.
+- A marked `.gitignore` block: instructions aliases are committed, skill links
+  are ignored. `--ignore=skills|all|none`.
+- Zero runtime dependencies, 59 tests, verified on Node 20, 22, 24 and 26.

package/CONVENTION.md

@@ -0,0 +1,89 @@
+# The agentlink convention
+
+A convention for repositories and home directories that several coding agents read. It exists so that a team can use different agents without maintaining a copy of the same instructions per agent.
+
+## The rule
+
+Two paths hold real content. Every harness-specific path that a tool reads is a symlink to one of them.
+
+```
+AGENTS.md                              instructions
+.agents/
+  skills/<skill-name>/SKILL.md         one directory per skill
+  <topic>.md                           optional extra docs
+  agentlink.json                       selection and link state (written by the CLI)
+```
+
+Links point at these, for example `CLAUDE.md -> AGENTS.md` and `.claude/skills/release -> ../../.agents/skills/release`. The links are relative, so a clone or a `git worktree` resolves them at any path.
+
+## Normative rules
+
+1. `AGENTS.md` at the root of the repository, or at `$HOME` for global instructions, is the only instructions file. Other names are links.
+2. Every skill is a directory under `.agents/skills/` containing `SKILL.md`. Supporting files stay inside that directory.
+3. A skill directory and its frontmatter `name` are the same lowercase-hyphenated string, 1 to 64 characters, matching `[a-z0-9]+(-[a-z0-9]+)*`.
+4. `SKILL.md` carries frontmatter with `name` and `description`. The description states what the skill does and when to use it.
+5. Never edit a file that is a symlink, and never create a sibling next to one. Edit the file it points at.
+6. Documentation that is not a skill goes under `.agents/`, or in an `AGENTS.md` inside the subdirectory it applies to.
+7. Run `agentlink sync` after adding, renaming, or moving a skill or doc.
+8. Harness instruction aliases are committed to git. Skill links are listed in `.gitignore` inside a block marked `# agentlink:begin`, which `agentlink sync` owns. Do not edit the block by hand.
+
+Rules 1 to 7 are format requirements, not preferences. Harnesses fail silently when they are broken: a skill whose name disagrees with its directory loads in some tools and not others, and an edited symlink leaves the canonical copy stale.
+
+Rule 8 is a trade-off rather than a requirement. Committing an instructions alias costs one small file and makes a fresh clone work for a teammate on a different harness. Committing skill links costs a symlink per skill per harness, and buys nothing that `agentlink sync` does not regenerate on demand.
+
+## The clause
+
+`agentlink sync` appends this block to `AGENTS.md`, between markers, so a future agent that has never seen the CLI can follow the convention. Paste it by hand if you are adopting the convention without the tool.
+
+```markdown
+<!-- agentlink:begin v1 -->
+## Agent docs and skills: one source of truth
+
+This repository keeps exactly one copy of every agent instruction file and skill.
+Paths such as `CLAUDE.md`, `GEMINI.md`, `.claude/skills/` and `.cursor/skills/`
+are symlinks maintained by `agentlink`. Never edit a symlink, and never create a
+file next to one — edit or create the source it points to.
+
+- **Instructions** live in `AGENTS.md` at the repository root.
+- **Skills** live in `.agents/skills/<skill-name>/SKILL.md`, one directory per skill.
+- **Extra documentation** goes under `.agents/` (for example `.agents/testing.md`),
+  or in an `AGENTS.md` in the subdirectory it applies to.
+- **Naming**: the skill directory and its frontmatter `name` are the same
+  lowercase-hyphenated string, 1-64 characters (`pdf-forms`, not `PDF_Forms`).
+  `SKILL.md` needs frontmatter with `name` and a `description` that states what
+  the skill does *and* when to use it. Keep scripts and references inside the
+  skill directory and link them with relative paths.
+- **After adding, renaming, or moving a skill or doc**, run `agentlink sync`
+  so every harness picks up the change.
+<!-- agentlink:end -->
+```
+
+The markers make the block idempotent and replaceable: sync rewrites the block in place when the convention changes, and never touches the text around it.
+
+## Adopting by hand
+
+```bash
+# 1. Instructions
+git mv CLAUDE.md AGENTS.md      # or merge the content by hand
+ln -s AGENTS.md CLAUDE.md
+
+# 2. Skills
+mkdir -p .agents/skills
+git mv .claude/skills/release .agents/skills/release
+ln -s ../../.agents/skills/release .claude/skills/release
+cat >> .gitignore <<'EOF'
+
+# agentlink:begin
+.claude/skills/
+# agentlink:end
+EOF
+
+# 3. The clause
+# paste the block above into AGENTS.md
+```
+
+Then run `agentlink sync` to create the remaining links and `agentlink doctor` to check the result. `doctor` exits non-zero when it finds an error, which makes it usable as a CI check on a repository that has adopted the convention.
+
+## Related
+
+The naming and layout rules for skills come from the [Agent Skills specification](https://agentskills.io/specification). The instructions file name comes from [agents.md](https://agents.md/). Both are implemented by most of the harnesses listed in the [README](README.md#what-gets-linked).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean Murphy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,177 @@
+# agentlink
+
+Every coding agent reads its own files. Claude Code wants `CLAUDE.md` and `.claude/skills/`. Codex reads `AGENTS.md` and `$HOME/.agents/skills`. The other fifteen picked something else again. Use two agents on one repository and you are keeping two copies of the same instructions, which drift.
+
+agentlink reduces that to one rule. Two paths are real:
+
+- `AGENTS.md` holds the instructions.
+- `.agents/skills/<name>/SKILL.md` holds each skill.
+
+Everything any harness reads is a symlink to one of those.
+
+## Quick start
+
+```bash
+cd your-project
+npx @thesmurph/agentlink init
+```
+
+`init` prints a checklist of all 17 known harnesses, with the ones installed on your machine already ticked. Confirm, and it creates `AGENTS.md` and `.agents/skills/`, appends a clause that tells future agents how the convention works, and symlinks each selected harness at the canonical files. The selection is saved in `.agents/agentlink.json`, so later runs need no input.
+
+After you add or move a skill:
+
+```bash
+npx @thesmurph/agentlink sync
+```
+
+## Commands
+
+```
+agentlink                pick harnesses (first run), then link
+agentlink init           create AGENTS.md + .agents/skills, migrate, link
+agentlink sync           re-link after adding or moving a skill
+agentlink fix            fold stray real copies into .agents, then link
+agentlink select         change which harnesses are linked
+agentlink list           every harness, where it reads from, whether it is installed
+agentlink doctor         drift, duplicates, invalid skills, broken links
+agentlink adopt          move an existing CLAUDE.md or GEMINI.md into AGENTS.md
+agentlink unlink         remove the links agentlink created
+```
+
+`init` does the whole conversion in one pass, including skills that already exist as real directories inside a harness folder. An orphan copy is moved into `.agents/skills/` and linked back. A copy identical to the canonical one is deleted. A copy that differs is reported and left alone until you have looked at it; `agentlink fix --force` drops the copy in favour of the canonical one.
+
+Options: `--global` (`-g`) for `$HOME` instead of a repository, `--harnesses a,b` to skip the picker, `--all`, `--detected`, `--dry-run`, `--yes`, `--force`, `--json`, `--no-clause`.
+
+## What gets linked
+
+Where a harness already reads `AGENTS.md` or `.agents/skills/`, agentlink writes nothing and reports the path as native. Links appear only for harnesses that need a file in a place of their own.
+
+| Harness | Project instructions | Project skills | Confirmed |
+| --- | --- | --- | --- |
+| Claude Code | CLAUDE.md | .claude/skills | yes |
+| OpenAI Codex CLI | native | native | yes |
+| Pi | native | native | yes |
+| Oh My Pi (omp) | native | .omp/skills | yes |
+| GitHub Copilot CLI | native | native | yes |
+| Cursor | native | .cursor/skills | no (skills) |
+| opencode | native | .opencode/skills | no (skills) |
+| Qwen Code | native | .qwen/skills | yes |
+| Kimi Code CLI | native | .kimi-code/skills | yes |
+| Kilo Code | native | .claude/skills | no (skills) |
+| Factory Droid | native | .factory/skills | yes |
+| Devin CLI | native | .devin/skills | yes |
+| Mastra Code | native | native | yes |
+| Grok CLI | native | .grok/skills | yes |
+| Qoder CLI | native | .qoder/skills | yes |
+| Antigravity CLI | native | .agent/skills | no (instructions, skills) |
+| Hermes | native | .hermes/skills | no (instructions, skills) |
+
+Confirmation is tracked per endpoint, not per harness, and per scope. A harness can have a documented project path and an undocumented global one. `agentlink list --json` prints the flag and the source URL for each endpoint, and `doctor` names every unverified path in your selection.
+
+The global scope is the weaker half of the table on purpose. Fewer vendors document where their home-directory instructions file lives, so `--global` links more speculative paths than a project does. Both scopes are listed in `list --json`.
+
+## Global scope
+
+`agentlink --global` applies the same convention to your home directory, so personal skills and standing preferences follow you into every repository:
+
+```
+~/AGENTS.md              global instructions
+~/.agents/skills/        personal skills
+```
+
+Each harness gets a link from its own home-directory file, for example `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. Harnesses that already read `~/.agents/skills/` get nothing, which is the point of the convention: the standard path is the one with the real files.
+
+## Git
+
+To git, a symlink is an ordinary tracked file. Nothing is ignored by default, so `agentlink` writes the rules for the paths it creates into a marked block in `.gitignore`. The default split is the one repositories already converge on, including langfuse, which commits `CLAUDE.md` as a symlink and ignores `.claude/skills/`.
+
+- Instructions aliases (`CLAUDE.md`, `.codex/AGENTS.md`) are committed. They are one small file, and they are what makes a fresh clone work for a teammate on a different harness.
+- Skill links are ignored. They are derived from `.agents/skills/` and multiply with every skill and harness, and their parent directories hold machine-local harness state.
+
+`--ignore=all` ignores both, for a repository where everyone runs `agentlink sync` after cloning. `--ignore=none` leaves `.gitignore` alone. The choice is stored in `.agents/agentlink.json`, so later runs keep it. `agentlink unlink` removes the block and leaves the rest of `.gitignore` untouched.
+
+```gitignore
+# agentlink:begin
+.claude/skills/
+.cursor/skills/
+# agentlink:end
+```
+
+One caveat about committing the aliases. Git checks symlinks out as plain text files when `core.symlinks` is false, which is how Git for Windows behaves until symlink support is enabled. A teammate there gets a `CLAUDE.md` whose contents are the string `AGENTS.md`. Teams with Windows checkouts should use `--ignore=all` and run `sync` after cloning.
+
+## CI
+
+`doctor` exits non-zero when it finds a problem, so a repository that has adopted the convention can check itself:
+
+```yaml
+- run: npx @thesmurph/agentlink doctor
+```
+
+The selection comes from `.agents/agentlink.json`, which is committed, so this works on a runner with no harnesses installed. `doctor --harnesses a,b` checks a declared set without depending on that file. With no selection and nothing installed there is nothing to check, and `doctor` says so instead of reporting a pass.
+
+## Safety
+
+None of this is done by overwriting.
+
+If a harness file already exists as a real file, sync leaves it alone and reports it as blocked. For an instructions file, `agentlink adopt` handles the migration: it renames `CLAUDE.md` to `AGENTS.md`, then links the old name back, so `git diff` shows one rename and you keep every line. When both files contain real content, adopt refuses and says so, because merging is a judgement call.
+
+`agentlink unlink` removes a symlink only when it still points at `AGENTS.md` or into `.agents/`. Anything that has become a real file gets kept and reported. Empty directories left behind are pruned.
+
+`sync` also removes links it created that are no longer wanted: deselect a harness with `select`, or delete a skill from `.agents/skills/`, and the leftover symlink is pruned on the next run rather than left dangling. Pruning only ever removes a symlink that still points into `.agents/`.
+
+Every command takes `--dry-run`.
+
+`doctor` exits non-zero when it finds an error, so it works as a CI check. A run that leaves an unresolved conflict (`init`, `fix`) also exits non-zero, which stops a scripted conversion instead of silently leaving two copies of a skill.
+
+## Limits worth knowing
+
+Claude Code has open reports of symlinked skill directories working but not appearing in `/skills`. The link is real and the content is reachable; the listing may miss it. If that turns out to matter, `agentlink unlink` restores the previous state and you can copy the skill directory instead.
+
+Harnesses that read `.agents/skills/` natively get no link at all, which means there is nothing for agentlink to repair if the harness changes its mind. `doctor` re-checks the table against what is selected, not against the vendor's current docs.
+
+The Agent Skills specification requires a skill's `name` to match its directory. Pi relaxes that rule so one skills directory can serve several tools. `doctor` warns when the two differ, since the other harnesses stay strict.
+
+## Repository layout
+
+```
+src/harnesses.ts   the path table, one row per harness, with a source URL
+src/link.ts        planning and creating symlinks
+src/convention.ts  the AGENTS.md clause, scaffolding, adoption
+src/doctor.ts      diagnostics and skill validation
+src/cli.ts         command dispatch and output
+src/ui.ts          the checkbox picker, no dependencies
+```
+
+Zero runtime dependencies. `npm run build` runs `tsc` into `dist/`.
+
+## Publishing
+
+The first release needs your npm credentials:
+
+```bash
+npm publish --access public --otp=<code from your authenticator>
+```
+
+The name is scoped (`agentlink` is too similar to the existing, empty `agent-link`, which npm's typosquat check rejects), so publishing needs `--access public`. Publishing is also 2FA-gated, and the token `npm login` writes by default does not bypass 2FA. A granular access token with "Bypass 2FA" enabled also works, if you would rather not type a code.
+
+After that, releases go through `.github/workflows/publish.yml` on a version tag, using trusted publishing so there is no token to rotate and provenance is attached automatically:
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+Configure it once on npmjs.com: package settings, Trusted publishing, GitHub Actions, with the workflow filename `publish.yml`.
+
+## Tests
+
+```bash
+npm test     # tsc, then node --test
+```
+
+Runs on Node 20, 22, 24 and 26, which CI checks. Bare `node --test` rather than `node --test test/`: the directory form resolves differently from Node 22 onward and fails.
+
+No test framework. The suite covers the path table invariants, symlink planning and repair, the `.gitignore` block, the AGENTS.md clause, duplicate migration, and the CLI run end to end in throwaway git repositories.
+
+## Adding a harness
+
+Add one row to `HARNESSES` in `src/harnesses.ts` and cite the documentation you read it from. State for each scope whether the harness reads the canonical path already, needs an alias, or has no documented answer. Rows with no answer print as unknown instead of writing a symlink somewhere the harness never looks.