github-spec-kit/extensions/agent-context

Coding Agent Context Extension

This bundled extension manages the coding agent context/instruction file (e.g. CLAUDE.md, .github/copilot-instructions.md, AGENTS.md, GEMINI.md, …) for the active integration.

It owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: <!-- SPECKIT START --> / <!-- SPECKIT END -->).

Why an extension?

Not every Spec Kit user wants Spec Kit to write into the coding agent's context file. Extracting this behavior into a dedicated extension lets users:

• Opt out entirely with specify extension disable agent-context — Spec Kit will then never create or modify the agent context file.
• Customize the markers by editing .specify/extensions/agent-context/agent-context-config.yml — both the Python layer and the bundled scripts honor the same context_markers value.
• Synchronize multiple agent anchors by setting context_files when a project intentionally uses more than one coding agent context file, such as AGENTS.md and CLAUDE.md.
• Refresh on demand with /speckit.agent-context.update, or automatically through the hooks declared in extension.yml (after_specify, after_plan).

Commands

Command	Description
speckit.agent-context.update	Refresh the managed section in the agent context file with the current plan path.

Configuration

All configuration flows through the extension's own config file at .specify/extensions/agent-context/agent-context-config.yml:

# Path to the coding agent context file managed by this extension
context_file: CLAUDE.md

# Optional list of coding agent context files to manage together.
# When non-empty, this takes precedence over context_file.
context_files:
  - AGENTS.md
  - CLAUDE.md

# Delimiters for the managed Spec Kit section
context_markers:
  start: "<!-- SPECKIT START -->"
  end: "<!-- SPECKIT END -->"

• context_file — the project-relative path to the coding agent context file, written by specify init and specify integration install.
• context_files — optional project-relative paths to multiple coding agent context files. When non-empty, the list takes precedence over context_file. Absolute paths, backslash separators, and .. path segments are rejected.
• context_markers.start / .end — the delimiters around the managed section. Edit these to use custom markers.

Requirements

The bundled update scripts require Python 3 with PyYAML for YAML/upsert processing (PowerShell can also use ConvertFrom-Yaml when available).

PyYAML ships with the specify CLI and is normally available via the same python3 interpreter. If a hook reports "PyYAML is required … not available in the current Python environment", it means the system python3 differs from the one used to install Spec Kit. To resolve, run:

pip install pyyaml
# or target the specific interpreter Spec Kit uses:
/path/to/speckit-python -m pip install pyyaml

Disable

specify extension disable agent-context

When disabled, Spec Kit skips context file creation, updates, and removal (the gates are inside upsert_context_section() and remove_context_section()). Disabled projects also ignore stale context_files values during command rendering so disabling the extension remains a complete opt-out.