Skip to content

Commit 75092d9

Browse files
rdmuellerrdmueller
authored
Merge pull request #407 from raifdmueller/refactor/move-agent-installation-docs
refactor: move agent installation docs to separate file
2 parents 8884f24 + a2120a6 commit 75092d9

3 files changed

Lines changed: 84 additions & 120 deletions

File tree

‎README.adoc‎

Lines changed: 2 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -25,77 +25,9 @@ Browse the full catalog of 60+ semantic anchors with interactive visualization,
2525
🔄 *Consistency*:: Ensure LLMs interpret concepts as intended
2626
🧠 *Depth*:: Activate multiple interconnected concepts with a single term
2727

28-
== 🤖 Installation for Coding Agents
28+
== 🤖 Using Anchors with Local LLMs
2929

30-
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.
31-
32-
=== Portable Baseline (Recommended)
33-
34-
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`.
35-
36-
First, copy the template and fill in your chosen anchors:
37-
38-
[source,bash]
39-
----
40-
cp skill/semantic-anchor-onboarding/assets/templates/anchor-block.md my-anchors.md
41-
# Edit my-anchors.md — replace {{PRIMARY_ANCHOR_*}} / {{PRIMARY_EXPLAINER_*}} placeholders
42-
----
43-
44-
Then run the installer:
45-
46-
[source,bash]
47-
----
48-
./skill/semantic-anchor-onboarding/scripts/install.sh \
49-
--source my-anchors.md \
50-
--target-dir . \
51-
--scope project
52-
----
53-
54-
=== link:https://openai.com/codex/[Codex]
55-
Codex supports `AGENTS.md` for repository instructions.
56-
57-
* Keep shared semantic anchors in `AGENTS.md`.
58-
* Use this as the canonical file when you want the same anchors to work across multiple agents.
59-
60-
=== link:https://docs.anthropic.com/en/docs/claude-code/memory[Claude Code]
61-
Claude Code uses `CLAUDE.md` for project memory and also supports hooks.
62-
63-
* *Static Context*: Mirror the same anchor block into `CLAUDE.md` if Claude Code is a target.
64-
* *Optional Hook*: If you want Claude to re-inject the managed block at session start, run:
65-
+
66-
[source,bash]
67-
----
68-
./skill/semantic-anchor-onboarding/scripts/install.sh \
69-
--source my-anchors.md \
70-
--target-dir . \
71-
--scope project \
72-
--claude-hook
73-
----
74-
75-
=== link:https://github.com/google-gemini/gemini-cli[Gemini CLI]
76-
Current Gemini CLI docs center on `GEMINI.md` and configurable context file names.
77-
78-
* *Native Gemini Context*: Mirror your selected anchors into `GEMINI.md`.
79-
* *Shared Cross-Agent Context*: Set Gemini's `context.fileName` to `AGENTS.md` if you want one portable project file.
80-
* Current Gemini CLI docs no longer describe `.gemini/skills/` or `gemini skills link` as the primary path for always-on instructions.
81-
82-
=== link:https://docs.cursor.com/en/context/rules[Cursor]
83-
Cursor supports `AGENTS.md` and project rules in `.cursor/rules/*.mdc`.
84-
85-
* Use `AGENTS.md` for shared, repo-wide semantic anchors.
86-
* Use `.cursor/rules/*.mdc` only when you need path-scoped or feature-scoped behavior inside Cursor itself.
87-
88-
=== link:https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions[GitHub Copilot]
89-
Copilot supports repository instruction files, and its coding agent can also consume `AGENTS.md`.
90-
91-
* Create or update `.github/copilot-instructions.md` when you want the same anchors to influence Copilot chat and review flows.
92-
* Keep `AGENTS.md` as the shared baseline if other coding agents are also in use.
93-
94-
=== link:https://docs.windsurf.com/windsurf/cascade/memories[Windsurf]
95-
Windsurf supports `AGENTS.md` alongside Windsurf Rules.
96-
97-
* Use `AGENTS.md` for portable project context shared with other agents.
98-
* Use Windsurf Rules only when you need editor-specific or scoped behavior.
30+
Most frontier LLMs already recognize semantic anchors from their training data. However, if you use local or smaller models (Llama, Mistral, Phi, etc.) that may not know all anchors, you can inject explicit definitions into your project's agent instruction files. See the link:docs/agent-installation.adoc[Agent Installation Guide] for setup instructions covering Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, and Windsurf.
9931

10032
== Quality Criteria
10133

‎README.md‎

Lines changed: 2 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -34,57 +34,9 @@ Semantic anchors are **well-defined terms, methodologies, or frameworks** that a
3434
- **Consistency** - Ensure LLMs interpret concepts as the community intends
3535
- **Context Compression** - Convey rich context concisely
3636

37-
## 🤖 Installation for Coding Agents
37+
## 🤖 Using Anchors with Local LLMs
3838

39-
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.
40-
41-
### Portable Baseline (Recommended)
42-
43-
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`.
44-
45-
First, copy the template and fill in your chosen anchors:
46-
47-
```bash
48-
cp skill/semantic-anchor-onboarding/assets/templates/anchor-block.md my-anchors.md
49-
# Edit my-anchors.md — replace {{PRIMARY_ANCHOR_*}} / {{PRIMARY_EXPLAINER_*}} placeholders
50-
```
51-
52-
Then run the installer:
53-
54-
```bash
55-
./skill/semantic-anchor-onboarding/scripts/install.sh \
56-
--source my-anchors.md \
57-
--target-dir . \
58-
--scope project
59-
```
60-
61-
### [Codex](https://openai.com/codex/)
62-
Codex supports `AGENTS.md` for repository instructions.
63-
- Keep shared semantic anchors in `AGENTS.md`.
64-
- Use this as the canonical file when you want the same anchors to work across multiple agents.
65-
66-
### [Claude Code](https://docs.anthropic.com/en/docs/claude-code/memory)
67-
Claude Code uses `CLAUDE.md` for project memory and also supports hooks.
68-
- **Static Context:** Mirror the same anchor block into `CLAUDE.md` if Claude Code is a target.
69-
- **Optional Hook:** If you want Claude to re-inject the managed block at session start, run:
70-
```bash
71-
./skill/semantic-anchor-onboarding/scripts/install.sh \
72-
--source my-anchors.md \
73-
--target-dir . \
74-
--scope project \
75-
--claude-hook
76-
```
77-
78-
### [Gemini CLI](https://github.com/google-gemini/gemini-cli)
79-
Current Gemini CLI docs center on `GEMINI.md` and configurable context file names.
80-
- **Native Gemini Context:** Mirror your selected anchors into `GEMINI.md`.
81-
- **Shared Cross-Agent Context:** Set Gemini's `context.fileName` to `AGENTS.md` if you want one portable project file.
82-
- Current Gemini CLI docs no longer describe `.gemini/skills/` or `gemini skills link` as the primary path for always-on instructions.
83-
84-
### [Cursor](https://docs.cursor.com/en/context/rules)
85-
Cursor supports `AGENTS.md` and project rules in `.cursor/rules/*.mdc`.
86-
- Use `AGENTS.md` for shared, repo-wide semantic anchors.
87-
- Use `.cursor/rules/*.mdc` only when you need path-scoped or feature-scoped behavior inside Cursor itself.
39+
Most frontier LLMs already recognize semantic anchors from their training data. However, if you use local or smaller models (Llama, Mistral, Phi, etc.) that may not know all anchors, you can inject explicit definitions into your project's agent instruction files. See the [Agent Installation Guide](docs/agent-installation.adoc) for setup instructions covering Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot, and Windsurf.
8840

8941
## 📚 Content Structure
9042

‎docs/agent-installation.adoc‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
= Installing Semantic Anchors for Coding Agents
2+
:toc:
3+
4+
== When Do You Need This?
5+
6+
Most frontier LLMs (GPT-4, Claude, Gemini) already have semantic anchors in their training data -- saying "TDD, London School" or "Clean Architecture" is enough to activate the right concepts.
7+
8+
However, *local or smaller LLMs* (Llama, Mistral, Phi, etc.) may not recognize all anchors reliably. For these models, you can inject explicit anchor definitions into your project's agent instruction files. This ensures consistent behavior regardless of the model's training data.
9+
10+
== Portable Baseline (Recommended)
11+
12+
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.
13+
14+
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`.
15+
16+
First, copy the template and fill in your chosen anchors:
17+
18+
[source,bash]
19+
----
20+
cp skill/semantic-anchor-onboarding/assets/templates/anchor-block.md my-anchors.md
21+
# Edit my-anchors.md — replace {{PRIMARY_ANCHOR_*}} / {{PRIMARY_EXPLAINER_*}} placeholders
22+
----
23+
24+
Then run the installer:
25+
26+
[source,bash]
27+
----
28+
./skill/semantic-anchor-onboarding/scripts/install.sh \
29+
--source my-anchors.md \
30+
--target-dir . \
31+
--scope project
32+
----
33+
34+
== Agent-Specific Setup
35+
36+
=== link:https://openai.com/codex/[Codex]
37+
Codex supports `AGENTS.md` for repository instructions.
38+
39+
* Keep shared semantic anchors in `AGENTS.md`.
40+
* Use this as the canonical file when you want the same anchors to work across multiple agents.
41+
42+
=== link:https://docs.anthropic.com/en/docs/claude-code/memory[Claude Code]
43+
Claude Code uses `CLAUDE.md` for project memory and also supports hooks.
44+
45+
* *Static Context*: Mirror the same anchor block into `CLAUDE.md` if Claude Code is a target.
46+
* *Optional Hook*: If you want Claude to re-inject the managed block at session start, run:
47+
+
48+
[source,bash]
49+
----
50+
./skill/semantic-anchor-onboarding/scripts/install.sh \
51+
--source my-anchors.md \
52+
--target-dir . \
53+
--scope project \
54+
--claude-hook
55+
----
56+
57+
=== link:https://github.com/google-gemini/gemini-cli[Gemini CLI]
58+
Current Gemini CLI docs center on `GEMINI.md` and configurable context file names.
59+
60+
* *Native Gemini Context*: Mirror your selected anchors into `GEMINI.md`.
61+
* *Shared Cross-Agent Context*: Set Gemini's `context.fileName` to `AGENTS.md` if you want one portable project file.
62+
* Current Gemini CLI docs no longer describe `.gemini/skills/` or `gemini skills link` as the primary path for always-on instructions.
63+
64+
=== link:https://docs.cursor.com/en/context/rules[Cursor]
65+
Cursor supports `AGENTS.md` and project rules in `.cursor/rules/*.mdc`.
66+
67+
* Use `AGENTS.md` for shared, repo-wide semantic anchors.
68+
* Use `.cursor/rules/*.mdc` only when you need path-scoped or feature-scoped behavior inside Cursor itself.
69+
70+
=== link:https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions[GitHub Copilot]
71+
Copilot supports repository instruction files, and its coding agent can also consume `AGENTS.md`.
72+
73+
* Create or update `.github/copilot-instructions.md` when you want the same anchors to influence Copilot chat and review flows.
74+
* Keep `AGENTS.md` as the shared baseline if other coding agents are also in use.
75+
76+
=== link:https://docs.windsurf.com/windsurf/cascade/memories[Windsurf]
77+
Windsurf supports `AGENTS.md` alongside Windsurf Rules.
78+
79+
* Use `AGENTS.md` for portable project context shared with other agents.
80+
* Use Windsurf Rules only when you need editor-specific or scoped behavior.

0 commit comments

Comments
 (0)