Skip to content

Share agent skills via a floating agents submodule - #677

Merged
alexander-yevsyukov merged 19 commits into
masterfrom
sharable-skills
Jun 2, 2026
Merged

Share agent skills via a floating agents submodule#677
alexander-yevsyukov merged 19 commits into
masterfrom
sharable-skills

Conversation

@alexander-yevsyukov

@alexander-yevsyukov alexander-yevsyukov commented Jun 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What & why

Shared agent skills, scripts, and guidelines were copied into every consumer repo by migrate, so each skill edit churned ~40 repos and competed with production/test diffs in pull requests. This moves them into a dedicated repository — SpineEventEngine/agents — mounted as a floating Git submodule at .agents/shared (tracking master) and exposed through symlinks. Updates now propagate on ./config/pull with no file churn in consumer pull requests.

Commits

  1. Group guidelines under .agents/guidelines/ — move the 16 flat guideline files into one directory (so a single symlink can later expose them) and rewrite all references. Pure reorganization; migrate still copies at this point.
  2. Submodule migration scaffolding — add adopt-shared-agents (idempotent: bootstraps a fresh repo, converts one that still has the old copies, or floats an existing one to agents@master) and the task plan.
  3. config consumes the agents submodule — config dogfoods .agents/shared; migrate is rewritten to delegate to adopt-shared-agents and copy only the Claude settings; drops all per-repo pruning and the rm -rf .agents (repo-local memory/ and tasks/ now survive); README/AGENTS document the model; adds docs/project.md.
  4. CONTRIBUTING.md copy-if-absent — migrate uses the initialize pattern for the static, org-wide CONTRIBUTING.md.

Rollout (no per-repo manual step)

Each consumer's next ./config/pull runs adopt-shared-agents, which removes the old copies, adds the .agents/shared submodule, creates the symlinks, and floats to agents@master.

Notes

  • SpineEventEngine/agents is created, seeded with history, initialized (README, docs, the author-skill meta-skill, dogfood .agents/.claude), and master is ruleset-protected.
  • Float design: .gitmodules uses branch = master, ignore = all — no pin bumps ever land in consumers.
  • Classic CI does not run skills, so it needs no float; agent runners and dev clones float via --remote. The agents repo is public, so cross-repo submodule checkout needs no extra token.
  • To verify on Windows CI: symlink + recursive submodule checkout (build-on-windows.yml).

🤖 Generated with Claude Code

alexander-yevsyukov and others added 4 commits June 2, 2026 01:30
@alexander-yevsyukov @claude
Group .agents guidelines under .agents/guidelines/
607c228 
Move the 16 flat shared guideline files (coding-guidelines, safety-rules, testing, _TOC, project.template, the widow-runt diagram, etc.) into `.agents/guidelines/` and rewrite every reference to the new paths across skills, AGENTS.md, README.md, .junie, scripts, .claude/commands, and the migrate script.

First step toward distributing shared agent content via a Git submodule (see .agents/tasks/share-skills-via-submodule.md): grouping the guidelines lets a single symlink later expose them from the shared repo instead of 16. Behaviour is unchanged here — migrate still copies the files, now from the subdirectory.

Cross-directory links in _TOC.md and version-policy.md are repo-rooted so they resolve whether guidelines/ is a real directory or a submodule symlink.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@alexander-yevsyukov @claude
Add shared-skills submodule migration scaffolding
048176f 
Add `adopt-shared-agents`, the one-time per-repo script that swaps copied agent content for the floating `.agents/shared` submodule plus symlinks, and the task plan tracking the migration. Not yet wired into `migrate` — applied once SpineEventEngine/agents exists.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@alexander-yevsyukov @claude
Make config consume the shared agents submodule
5e1006c 
Switch config's own agent tooling to the floating .agents/shared submodule (the SpineEventEngine/agents repo) via symlinks, replacing the copied skills, scripts, guidelines, and Claude commands/agents. Add docs/project.md (config's real description) linked from .agents/project.md.

Rewrite migrate: instead of copying .agents and .claude, it runs the idempotent adopt-shared-agents against the consumer (bootstrapping a fresh repo, converting an old copied one, or floating an existing one to agents@master) and copies only the Claude settings. Drop all per-repo pruning; stop rm -rf .agents so repo-local memory/ and tasks/ survive. .junie is now a selective copy.

adopt-shared-agents: default to HTTPS; allow bootstrapping a repo with no pre-existing .agents. README and AGENTS document the submodule model and how to initialize it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@alexander-yevsyukov @claude
Copy CONTRIBUTING.md to consumers only if absent
a69d1bd 
CONTRIBUTING.md is identical and static across the org, so migrate now uses the initialize (copy-if-absent) pattern for it instead of overwriting on every pull — which also avoids clobbering a deliberately customized copy. The initialize helper is hoisted to the top of the Common section so it is available at that point.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@alexander-yevsyukov alexander-yevsyukov self-assigned this Jun 2, 2026
chatgpt-codex-connector[bot]
chatgpt-codex-connector Bot reviewed Jun 2, 2026
View reviewed changes

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a69d1bdb81

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread adopt-shared-agents
@alexander-yevsyukov @claude
Apply pre-PR doc review feedback
dc5161f 
Address review-docs should-fixes on the agents-submodule docs:

- Convert external SpineEventEngine/agents links to footnote style ([agents-repo]) per the writer convention, in README.md, AGENTS.md, and docs/project.md.

- Drop .claude/skills from the README symlink enumeration: it is a 2-hop alias of .agents/skills, not a direct submodule path, and the sibling docs already omit it.

- Reflow the split 'git submodule update --remote' code span in docs/project.md onto one line.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Moves shared AI-agent assets (skills, scripts, guidelines, Claude commands/agents) out of per-repo copies and into a floating Git submodule (.agents/shared) that tracks SpineEventEngine/agents@master, exposed via symlinks to eliminate cross-repo churn when updating skills.

Changes:

  • Introduce adopt-shared-agents and wire migrate to initialize/float the shared submodule + symlinks.
  • Update entrypoint docs/references (README.md, AGENTS.md, Copilot/Junie docs) to point at .agents/guidelines/**.
  • Remove in-repo copies of shared skills/scripts/guidelines (now provided by .agents/shared).

Reviewed changes

Copilot reviewed 106 out of 107 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
README.md Documents shared agent content coming from floating .agents/shared submodule and exposed via symlinks.
migrate Stops copying shared agent content; delegates setup to adopt-shared-agents; preserves repo-local memory/tasks.
docs/project.md Adds repo-local project description for config and describes the shared-agents submodule model.
AGENTS.md Updates references to .agents/guidelines/** and documents submodule initialization.
adopt-shared-agents New idempotent migration script to add submodule + create symlinks + seed/move project.md.
.junie/guidelines.md Updates TOC link to .agents/guidelines/_TOC.md.
.gitmodules Adds floating submodule definition for .agents/shared tracking master and ignoring gitlink changes.
.github/copilot-instructions.md Updates guidelines index reference to .agents/guidelines/_TOC.md.
.claude/commands/write-docs.md Removed (now provided via shared submodule symlink).
.claude/commands/update-copyright.md Removed (now provided via shared submodule symlink).
.claude/commands/run-build.md Removed (now provided via shared submodule symlink).
.claude/commands/review-docs.md Removed (now provided via shared submodule symlink).
.claude/commands/raise-coverage.md Removed (now provided via shared submodule symlink).
.claude/commands/pre-pr.md Removed (now provided via shared submodule symlink).
.claude/commands/move-files.md Removed (now provided via shared submodule symlink).
.claude/commands/java-to-kotlin.md Removed (now provided via shared submodule symlink).
.claude/commands/dependency-update.md Removed (now provided via shared submodule symlink).
.claude/commands/bump-version.md Removed (now provided via shared submodule symlink).
.claude/commands/bump-gradle.md Removed (now provided via shared submodule symlink).
.claude/agents/review-docs.md Removed (now provided via shared submodule symlink).
.claude/agents/kotlin-review.md Removed (now provided via shared submodule symlink).
.claude/agents/dependency-audit.md Removed (now provided via shared submodule symlink).
.agents/version-policy.md Removed (now provided via shared submodule symlink).
.agents/testing.md Removed (now provided via shared submodule symlink).
.agents/tasks/enforce-max-line-length.md Updates task-plan references to the new .agents/guidelines/** layout.
.agents/skills/writer/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/writer/assets/templates/kotlin-java-example.md Removed (now provided via shared submodule symlink).
.agents/skills/writer/assets/templates/kdoc-example.md Removed (now provided via shared submodule symlink).
.agents/skills/writer/assets/templates/doc-page.md Removed (now provided via shared submodule symlink).
.agents/skills/writer/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/version-bumped/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/version-bumped/scripts/version-bumped.sh Removed (now provided via shared submodule symlink).
.agents/skills/version-bumped/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/update-copyright/tests/test_update_copyright.py Removed (now provided via shared submodule symlink).
.agents/skills/update-copyright/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/update-copyright/scripts/update_copyright.py Removed (now provided via shared submodule symlink).
.agents/skills/update-copyright/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/review-docs/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/review-docs/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/raise-coverage/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/raise-coverage/references/coverage-signals.md Removed (now provided via shared submodule symlink).
.agents/skills/raise-coverage/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/pre-pr/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/pre-pr/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/move-files/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/move-files/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/kotlin-review/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/kotlin-review/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/kotlin-engineer/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/kotlin-engineer/references/idioms.md Removed (now provided via shared submodule symlink).
.agents/skills/kotlin-engineer/references/coroutines.md Removed (now provided via shared submodule symlink).
.agents/skills/kotlin-engineer/references/build-setup.md Removed (now provided via shared submodule symlink).
.agents/skills/kotlin-engineer/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/java-to-kotlin/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/java-to-kotlin/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/gradle-review/spine-task-conventions.md Removed (now provided via shared submodule symlink).
.agents/skills/gradle-review/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/gradle-review/practices/tasks.md Removed (now provided via shared submodule symlink).
.agents/skills/gradle-review/practices/README.md Removed (now provided via shared submodule symlink).
.agents/skills/gradle-review/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/dependency-update/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/dependency-update/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/dependency-audit/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/dependency-audit/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/check-links/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/check-links/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/bump-version/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/bump-version/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/bump-gradle/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/bump-gradle/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/skills/api-discovery/SKILL.md Removed (now provided via shared submodule symlink).
.agents/skills/api-discovery/agents/openai.yaml Removed (now provided via shared submodule symlink).
.agents/scripts/update-copyright.sh Removed (now provided via shared submodule symlink).
.agents/scripts/sanitize-source-code.sh Removed (now provided via shared submodule symlink).
.agents/scripts/publish-version-gate.sh Removed (now provided via shared submodule symlink).
.agents/scripts/protect-version-file.sh Removed (now provided via shared submodule symlink).
.agents/scripts/pre-pr-gate.sh Removed (now provided via shared submodule symlink).
.agents/scripts/api-discovery/update-sibling Removed (now provided via shared submodule symlink).
.agents/scripts/api-discovery/README.md Removed (now provided via shared submodule symlink).
.agents/scripts/api-discovery/lib/common.sh Removed (now provided via shared submodule symlink).
.agents/scripts/api-discovery/extract-sources Removed (now provided via shared submodule symlink).
.agents/scripts/api-discovery/discover Removed (now provided via shared submodule symlink).
.agents/scripts/api-discovery/clean-cache Removed (now provided via shared submodule symlink).
.agents/scripts/api-discovery/.gitignore Removed (now provided via shared submodule symlink).
.agents/safety-rules.md Removed (now provided via shared submodule symlink).
.agents/running-builds.md Removed (now provided via shared submodule symlink).
.agents/refactoring-guidelines.md Removed (now provided via shared submodule symlink).
.agents/quick-reference-card.md Removed (now provided via shared submodule symlink).
.agents/project.template.md Removed (now provided via shared submodule symlink).
.agents/project-structure-expectations.md Removed (now provided via shared submodule symlink).
.agents/jvm-project.md Removed (now provided via shared submodule symlink).
.agents/documentation-tasks.md Removed (now provided via shared submodule symlink).
.agents/documentation-guidelines.md Removed (now provided via shared submodule symlink).
.agents/common-tasks.md Removed (now provided via shared submodule symlink).
.agents/coding-guidelines.md Removed (now provided via shared submodule symlink).
.agents/advanced-safety-rules.md Removed (now provided via shared submodule symlink).
.agents/_TOC.md Removed (now provided via shared submodule symlink as .agents/guidelines/_TOC.md).

Comment thread docs/project.md
Comment thread adopt-shared-agents Outdated
@alexander-yevsyukov @claude
Address review feedback (round 1)
6ab615b 
- adopt-shared-agents: during adoption, also remove the pre-regroup flat .agents/*.md guideline files a consumer carried under the old copied layout, so migrating repos don't retain stale shared config (Codex).

- adopt-shared-agents: recreate .claude/skills and .junie/skills unconditionally so a stale real directory from an old copy-based setup is replaced by the symlink (Copilot).

- docs/project.md: make the jvm-project.md link relative (../) so it resolves from the docs/ directory instead of docs/.agents/... (Copilot).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 3 comments.

Comment thread adopt-shared-agents
Comment thread migrate Outdated
Comment thread adopt-shared-agents
@alexander-yevsyukov @claude
Address review feedback (round 2)
757c1e4 
- adopt-shared-agents: link() no longer rm -rf's untracked content — a non-symlink in the way is removed only if tracked (recoverable via Git), otherwise the script stops and asks the user to move it aside, preventing data loss (Copilot).

- adopt-shared-agents: set submodule branch=master unconditionally so an already-registered .agents/shared that lacks/misconfigures it is corrected before --remote runs (Copilot).

- migrate: treat an adopt-shared-agents failure as fatal (exit) instead of warning-and-continuing, so a half-migrated repo is never reported as success (Copilot).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 3 comments.

Comment thread adopt-shared-agents
Comment thread migrate
Comment thread AGENTS.md Outdated
@alexander-yevsyukov @claude
Address review feedback (round 3)
5799da5 
- adopt-shared-agents: persist submodule.url and run 'git submodule sync' so an already-registered .agents/shared pointing at a different URL is corrected to the requested AGENTS_URL before --remote runs (Copilot).

- migrate: remove any stale ../.claude/settings-hugo.json left by a previous migrate; it is a config-internal template, never distributed as-is (Copilot).

- AGENTS.md: scope the fresh-clone init command to '.agents/shared' instead of '--remote --recursive' so it does not float other submodules such as config/ (Copilot).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@alexander-yevsyukov

alexander-yevsyukov commented Jun 2, 2026

Copy link
Copy Markdown
Contributor Author

@codex, review.

Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 2 comments.

Comment thread adopt-shared-agents Outdated
Comment thread adopt-shared-agents Outdated
chatgpt-codex-connector[bot]
chatgpt-codex-connector Bot reviewed Jun 2, 2026
View reviewed changes

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5799da5e05

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread adopt-shared-agents Outdated
Comment thread adopt-shared-agents
@alexander-yevsyukov @claude
Address review feedback (round 4)
7333202 
- adopt-shared-agents: preflight now asserts the CWD is the repository root (git toplevel == pwd), so running from a subdirectory can't create/remove paths in the wrong place (Copilot).

- adopt-shared-agents: stop staging the submodule gitlink — only .gitmodules and the symlinks are staged. The initial pin is recorded by 'git submodule add'; re-staging the floated commit would commit pin bumps on every run, the churn this design avoids (Copilot).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 2 comments.

Comment thread README.md Outdated
Comment thread adopt-shared-agents Outdated
@alexander-yevsyukov @claude
Address review feedback (round 5)
3a13ad2 
- adopt-shared-agents: never overwrite an existing repo-local docs/project.md. Seed it from the shared template only when absent; otherwise just (re)create the .agents/project.md symlink. A legacy real .agents/project.md is moved to docs/ only if no docs/project.md already exists, else it's removed in favour of the existing one (Codex).

The other Codex thread (staging floated submodule pins) was already addressed in round 4 (7333202), which removed 'git add $SHARED_PATH'.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 2 comments.

Comment thread adopt-shared-agents
Comment thread AGENTS.md Outdated
@alexander-yevsyukov @claude
Address review feedback (round 10)
fc5b2f6 
- adopt-shared-agents: link() now refuses to remove a tracked directory that contains untracked files — git rm -r would drop only tracked files and the following rm -rf would destroy the untracked ones. Abort with a clear message (gitignored cruft still allowed) so 'untracked content is never destroyed' actually holds (Copilot).

- AGENTS.md: project.md guidance now points at docs/project.md (which .agents/project.md symlinks to), so users edit the real file instead of replacing the symlink or fighting the migration script (Copilot).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 1 comment.

Comment thread adopt-shared-agents
@alexander-yevsyukov @claude
Address review feedback (round 11)
51ecf2d 
- adopt-shared-agents: apply the same untracked-files guard to remove_tracked that link() got in round 10, so the script fails fast (before any git rm) if a tracked directory holds untracked, non-ignored files — preventing a partial migration where tracked content is removed and a later step aborts (Copilot).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 7 comments.

Comment thread README.md
Comment thread AGENTS.md
Comment thread AGENTS.md
Comment thread AGENTS.md
Comment thread .junie/guidelines.md
Comment thread .github/copilot-instructions.md Outdated
Comment thread docs/project.md
@alexander-yevsyukov

alexander-yevsyukov commented Jun 2, 2026

Copy link
Copy Markdown
Contributor Author

Re: the 7 comments about .agents/guidelines/… link targets and directory-symlink navigability — declining as by-design.

These are repo-rooted paths for agents working in a checked-out tree (Claude/Codex/Junie), where .agents/guidelines (a symlink into the .agents/shared submodule) resolves on the filesystem. They follow the .agents/guidelines/ convention used across every skill and _TOC.md.

The suggested fix — pointing at .agents/shared/guidelines/… — wouldn't help: .agents/shared is a submodule (gitlink), so that path isn't browsable in the parent repo's GitHub UI either. It would only expose the mount as an implementation detail and diverge from the convention, with no actual navigability gain. The only thing that resolves in the web UI is an absolute URL into the agents repo, which in turn doesn't resolve on a checked-out tree (what agents actually use).

So the local .agents/guidelines/… path is intentional and correct for the real consumers. Resolving these threads as by-design.

Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 3 comments.

Comment thread adopt-shared-agents
Comment thread adopt-shared-agents
Comment thread migrate Outdated
@alexander-yevsyukov @claude
Address review feedback (round 12)
efa85d4 
- adopt-shared-agents: fail clearly when `.agents/shared` exists on disk or
  in the index but is not a registered submodule, instead of letting
  `git submodule add` abort with an opaque error.
- adopt-shared-agents: handle an untracked legacy `.agents/project.md` —
  relocate it with plain mv/rm + `git add` rather than `git mv`/`git rm`,
  which would abort the migration on an untracked path.
- migrate: correct comment wording (`adopt-shared-agents` runs earlier in the
  script, not "below").

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 1 comment.

Comment thread adopt-shared-agents Outdated
@alexander-yevsyukov @claude
Address review feedback (round 13)
6aedb55 
adopt-shared-agents: collapse the "path exists but is not a registered
submodule" error onto a single, properly quoted guidance line so both the
`rm -rf` and `git rm --cached` commands read and copy cleanly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated 2 comments.

Comment thread migrate
Comment thread .github/copilot-instructions.md Outdated
@alexander-yevsyukov @claude
Address review feedback (round 14)
d27b7ec 
- migrate: pass the canonical `agents` remote URL explicitly to
  `adopt-shared-agents` so an ambient `AGENTS_URL` in a shell/CI environment
  cannot silently redirect a consumer to an unintended fork during an automatic
  `./config/pull`. An explicit argument wins over the env var.
- copilot-instructions.md: drop the stale "Hugo repos do not include this
  file" note about `_TOC.md`. Shared guidelines (including the TOC) are now
  mounted via the `.agents/shared` submodule for every repo, Hugo included.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Copilot AI reviewed Jun 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 106 out of 107 changed files in this pull request and generated no new comments.

@alexander-yevsyukov
alexander-yevsyukov merged commit 1bedb88 into master Jun 2, 2026
4 checks passed
@alexander-yevsyukov
alexander-yevsyukov deleted the sharable-skills branch June 2, 2026 15:13
@alexander-yevsyukov alexander-yevsyukov mentioned this pull request Jun 2, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@chatgpt-codex-connector chatgpt-codex-connector[bot] chatgpt-codex-connector[bot] left review comments
@armiol armiol armiol approved these changes

Assignees

@alexander-yevsyukov alexander-yevsyukov

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@alexander-yevsyukov @armiol