The point of this skill is not just package installation. The real job is to
make the repo's agent contract coherent:
the toolchain is installed where it belongs
AGENTS.md
tells agents when and how to use it
inline
@context
is treated as the required structured layer
supporting refs stay unconstrained and user-owned
Do not invent required sidecar document schemas. Do not require
.ctx.md
.
Refs can point to Markdown, HTML, text, diagrams, exported docs, or any other
resolvable file the repo uses.
When to use
Use this skill when the user asks to:
install or adopt
codecontext
update a repo's
AGENTS.md
or agent guidance around
@context
audit a project's current
codecontext
setup
reconcile a mismatch between codecontext tooling and repo instructions
improve how agents discover decisions, risks, assumptions, and history
Outcome
By the end of this workflow, the repo should have:
a clear
AGENTS.md
section for
codecontext
a sane CLI workflow for agents
the right enforcement surface for the repo's languages and toolchain
no misleading guidance about structured sidecar docs
Workflow
1. Audit the current state
Inspect:
package manager and workspace layout
whether the repo already depends on
@recallnet/codecontext-cli
whether the repo already depends on
@recallnet/codecontext-eslint-plugin
whether the repo already has Python, Go, Rust, or other language-native
whether the repo already has Python, Go, Ruby, Rust, or other language-native
checkers where
codecontext
enforcement belongs
whether ESLint is present and where its shared config lives
whether
AGENTS.md
exists at repo root and in subtrees/worktrees
whether existing agent docs already mention
@context
,
codecontext
, ADRs,
contexts/
, or decision logs
Look for the two common failure modes:
tool installed, but no agent workflow or guidance
guidance exists, but it is stale, contradictory, or points to a policy that
does not exist
2. Decide the installation surface
Install the minimum useful surface:
@recallnet/codecontext-cli
when agents should run
--scope
,
--diff
, or
--report
@recallnet/codecontext-eslint-plugin
when the repo uses ESLint and wants
comment validation
a language-native checker or analyzer when the repo's main enforcement
surface is Python, Go, Rust, or something else outside ESLint
@recallnet/codecontext-parser
only if the repo has custom code that imports
parser APIs directly
Do not add packages the repo is not going to use.
3. Fix
AGENTS.md
before or alongside package changes
codecontext
setup is incomplete without agent instructions.
Every repo-level
AGENTS.md
section should cover:
what
@context
is for
when annotations are required
a small preferred taxonomy
the pre-edit and post-edit workflow
what refs are and are not
anti-patterns
If subtree
AGENTS.md
files point to a repo-level policy, make sure that
policy actually exists.
Recommended
AGENTS.md
contract
Keep it short. A good section usually fits in 8-14 bullets.
Use something close to this:
-
**
codecontext
**
Use inline
@context
annotations for non-obvious,
high-value reasoning that future edits could easily erase.
-
Required for:
-
critical decision logic and invariants
-
security-sensitive behavior and hard-won lessons
-
external integration quirks and contract mismatches
-
regression guards explaining why a simpler change would be wrong
-
Preferred forms:
@context decision
,
@context risk
,
@context requirement
,
@context history
-
Keep notes short and specific: what is true, why it matters, and what
would break if changed
-
Use
{@link ...}
for supporting material when helpful, but refs are just pointers
to repo files or docs. Do not require any special doc schema.
-
Before editing critical files, run:
npx @recallnet/codecontext-cli --scope <file>
-
After editing, run:
npx @recallnet/codecontext-cli --diff HEAD <file>
-
For broader orientation in larger repos, run:
npx @recallnet/codecontext-cli --report
-
Do not use
@context
for obvious narration, duplicated ADR prose, or
generic comments.
Adjust the taxonomy only if the repo clearly needs more than the baseline
(
decision
,
risk
,
requirement
,
history
). Add extra categories sparingly.
Guidance for repos with ADRs or large docs trees
If the repo already uses ADRs, plans, runbooks, or architecture docs:
keep
@context
as the inline agent-facing layer
treat refs as optional expansion targets
do not tell agents to browse the entire docs tree by default
do not mirror whole ADRs inline
The correct model is:
@context
carries the structured local signal
refs point to arbitrary supporting material
agents expand refs only when needed
Refs policy
Be explicit:
refs are allowed to point to
.md
,
.html
,
.txt
, diagrams, exports, or
other repo artifacts
refs are not required on every annotation
refs should not impose a schema on the target file
Do not write guidance that implies:
.ctx.md
is required
frontmatter is required
the linked file must be machine-parseable
CLI workflow guidance
Recommend these commands in agent docs when the CLI is installed:
npx @recallnet/codecontext-cli
--scope
path/to/file.ts
npx @recallnet/codecontext-cli
--diff
HEAD path/to/file.ts
npx @recallnet/codecontext-cli
--report
Use
--report
for repo orientation and decision review. Use
--scope
and
--diff
around concrete edits.
Enforcement guidance
If the repo already has a shared ESLint config, integrate the plugin there.
Prefer enforcing syntax and stale/invalid ref checks centrally rather than
telling agents to self-police.
If the repo does not use ESLint, do not force it just for
codecontext
.
Prefer the native enforcement surface for the repo's actual stack:
Python repo: native checker or PyPI-distributed tool
Go repo: analyzer /
golangci-lint
integration
Ruby repo: native checker gem or RuboCop-style integration
Rust repo: crate / Clippy-style integration
mixed or tool-agnostic repo: CLI workflow may be enough initially
The important question is not "did we install the ESLint plugin?"
It is "what actually enforces
@context
correctness in this ecosystem?"
What to look for in a review
Flag these as setup defects:
child
AGENTS.md
files pointing to a missing repo policy
instructions that mention
@context
but give no workflow
workflow guidance that ignores
--report
in large repos
guidance that treats linked docs as required structured sidecars
package installs without corresponding agent documentation
documentation that tells agents to read giant ADR/doc trees by default
Delivery
When you finish setup or audit work:
state what was installed or changed
call out any stale or contradictory
AGENTS.md
guidance you fixed
mention any remaining gaps
if you did not install an enforcement surface, explain why
Default recommendation
If the repo has no existing
codecontext
guidance, prefer creating a
codecontext-setup
section in the root
AGENTS.md
rather than scattering
instructions across multiple child docs first.