Skip to content

agent-installation.adoc

Latest commit

 

History

History
80 lines (57 loc) · 3.51 KB

agent-installation.adoc

File metadata and controls

80 lines (57 loc) · 3.51 KB

Installing Semantic Anchors for Coding Agents

Table of Contents

When Do You Need This?

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.

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.

Portable Baseline (Recommended)

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.

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:

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:

./skill/semantic-anchor-onboarding/scripts/install.sh \
  --source my-anchors.md \
  --target-dir . \
  --scope project

Agent-Specific Setup

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

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:

    ./skill/semantic-anchor-onboarding/scripts/install.sh \
  --source my-anchors.md \
  --target-dir . \
  --scope project \
  --claude-hook

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

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.

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.

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.