Merge pull request #388 from cpoepke/feat/onboarding-skill-and-translator

feat: add onboarding skill, translator skill, and agent installation docs

Author: rdmueller

.gitattributes

@@ -0,0 +1,3 @@
+# Mark plugin skill copies as generated so GitHub does not count them
+# toward language statistics or include them in diffs by default.
+plugins/semantic-anchors/skills/** linguist-generated=true

README.adoc

@@ -25,6 +25,78 @@ Browse the full catalog of 60+ semantic anchors with interactive visualization,
 🔄 *Consistency*:: Ensure LLMs interpret concepts as intended
 🧠 *Depth*:: Activate multiple interconnected concepts with a single term
 
+== 🤖 Installation for Coding Agents
+
+For the widest compatibility, install anchors into a project-level `AGENTS.md` first, then add agent-specific mirrors only where the official docs say they help.
+
+=== Portable Baseline (Recommended)
+
+Use the bundled installer to inject a managed anchor block into the best available project instruction file. If none exists yet, it creates `AGENTS.md`.
+
+First, copy the template and fill in your chosen anchors:
+
+[source,bash]
+----
+cp skill/semantic-anchor-onboarding/assets/templates/anchor-block.md my-anchors.md
+# Edit my-anchors.md — replace {{PRIMARY_ANCHOR_*}} / {{PRIMARY_EXPLAINER_*}} placeholders
+----
+
+Then run the installer:
+
+[source,bash]
+----
+./skill/semantic-anchor-onboarding/scripts/install.sh \
+  --source my-anchors.md \
+  --target-dir . \
+  --scope project
+----
+
+=== link:https://openai.com/codex/[Codex]
+Codex supports `AGENTS.md` for repository instructions.
+
+* Keep shared semantic anchors in `AGENTS.md`.
+* Use this as the canonical file when you want the same anchors to work across multiple agents.
+
+=== link:https://docs.anthropic.com/en/docs/claude-code/memory[Claude Code]
+Claude Code uses `CLAUDE.md` for project memory and also supports hooks.
+
+* *Static Context*: Mirror the same anchor block into `CLAUDE.md` if Claude Code is a target.
+* *Optional Hook*: If you want Claude to re-inject the managed block at session start, run:
++
+[source,bash]
+----
+./skill/semantic-anchor-onboarding/scripts/install.sh \
+  --source my-anchors.md \
+  --target-dir . \
+  --scope project \
+  --claude-hook
+----
+
+=== link:https://github.com/google-gemini/gemini-cli[Gemini CLI]
+Current Gemini CLI docs center on `GEMINI.md` and configurable context file names.
+
+* *Native Gemini Context*: Mirror your selected anchors into `GEMINI.md`.
+* *Shared Cross-Agent Context*: Set Gemini's `context.fileName` to `AGENTS.md` if you want one portable project file.
+* Current Gemini CLI docs no longer describe `.gemini/skills/` or `gemini skills link` as the primary path for always-on instructions.
+
+=== link:https://docs.cursor.com/en/context/rules[Cursor]
+Cursor supports `AGENTS.md` and project rules in `.cursor/rules/*.mdc`.
+
+* Use `AGENTS.md` for shared, repo-wide semantic anchors.
+* Use `.cursor/rules/*.mdc` only when you need path-scoped or feature-scoped behavior inside Cursor itself.
+
+=== link:https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions[GitHub Copilot]
+Copilot supports repository instruction files, and its coding agent can also consume `AGENTS.md`.
+
+* Create or update `.github/copilot-instructions.md` when you want the same anchors to influence Copilot chat and review flows.
+* Keep `AGENTS.md` as the shared baseline if other coding agents are also in use.
+
+=== link:https://docs.windsurf.com/windsurf/cascade/memories[Windsurf]
+Windsurf supports `AGENTS.md` alongside Windsurf Rules.
+
+* Use `AGENTS.md` for portable project context shared with other agents.
+* Use Windsurf Rules only when you need editor-specific or scoped behavior.
+
 == Quality Criteria
 
 A good semantic anchor is:

README.md

@@ -34,6 +34,58 @@ Semantic anchors are **well-defined terms, methodologies, or frameworks** that a
 - **Consistency** - Ensure LLMs interpret concepts as the community intends
 - **Context Compression** - Convey rich context concisely
 
+## 🤖 Installation for Coding Agents
+
+For the widest compatibility, install anchors into a project-level `AGENTS.md` first, then add agent-specific mirrors only where the official docs say they help.
+
+### Portable Baseline (Recommended)
+
+Use the bundled installer to inject a managed anchor block into the best available project instruction file. If none exists yet, it creates `AGENTS.md`.
+
+First, copy the template and fill in your chosen anchors:
+
+```bash
+cp skill/semantic-anchor-onboarding/assets/templates/anchor-block.md my-anchors.md
+# Edit my-anchors.md — replace {{PRIMARY_ANCHOR_*}} / {{PRIMARY_EXPLAINER_*}} placeholders
+```
+
+Then run the installer:
+
+```bash
+./skill/semantic-anchor-onboarding/scripts/install.sh \
+  --source my-anchors.md \
+  --target-dir . \
+  --scope project
+```
+
+### [Codex](https://openai.com/codex/)
+Codex supports `AGENTS.md` for repository instructions.
+- Keep shared semantic anchors in `AGENTS.md`.
+- Use this as the canonical file when you want the same anchors to work across multiple agents.
+
+### [Claude Code](https://docs.anthropic.com/en/docs/claude-code/memory)
+Claude Code uses `CLAUDE.md` for project memory and also supports hooks.
+- **Static Context:** Mirror the same anchor block into `CLAUDE.md` if Claude Code is a target.
+- **Optional Hook:** If you want Claude to re-inject the managed block at session start, run:
+  ```bash
+  ./skill/semantic-anchor-onboarding/scripts/install.sh \
+    --source my-anchors.md \
+    --target-dir . \
+    --scope project \
+    --claude-hook
+  ```
+
+### [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+Current Gemini CLI docs center on `GEMINI.md` and configurable context file names.
+- **Native Gemini Context:** Mirror your selected anchors into `GEMINI.md`.
+- **Shared Cross-Agent Context:** Set Gemini's `context.fileName` to `AGENTS.md` if you want one portable project file.
+- Current Gemini CLI docs no longer describe `.gemini/skills/` or `gemini skills link` as the primary path for always-on instructions.
+
+### [Cursor](https://docs.cursor.com/en/context/rules)
+Cursor supports `AGENTS.md` and project rules in `.cursor/rules/*.mdc`.
+- Use `AGENTS.md` for shared, repo-wide semantic anchors.
+- Use `.cursor/rules/*.mdc` only when you need path-scoped or feature-scoped behavior inside Cursor itself.
+
 ## 📚 Content Structure
 
 The catalog is organized as: