[FEATURE]: Package-level context and instruction file for SDKs

[DimaKH]

Summary

AGENTS.md is emerging as a great way to tell AI agents how to work in this repository.

What’s still missing is a standard way for SDKs and libraries to tell agents how to work with them – for the exact version that’s installed, not whatever the model was trained on.

This proposal suggests a companion convention to the existing spec:

• AGENTS.md → project-level instructions (“how to work here”)
• Package-level context file (e.g. CONTEXT.md) → SDK/library-level semantics (“how to use this library, in this version”)

The idea is that such a context file would ship with packages (including internal libs) and be automatically discoverable by tools that already support AGENTS.md.

Problem: integrating SDKs without a package-level context file

Today, when an agent tries to help integrate an SDK or library, it usually relies on:

• Frozen training-time knowledge
  The model may “remember” an SDK from training, but for a different version. It can suggest deprecated APIs, old patterns, or miss new required steps.

• Human-first documentation
  READMEs and docs are written for humans: they mix install steps, badges, marketing text, changelogs, screenshots, etc.
  For an agent, the “how to correctly integrate this here” signal is buried in noise and spread across pages.

• Missing design intent and constraints
  API references and comments tell you what functions/types exist, but not:

  • how to think about the SDK (mental model),
  • which pieces are public surface vs internal plumbing,
  • which patterns are recommended vs legacy,
  • what ordering rules and invariants must be respected (e.g. “call this before that”, “never do this in a request”, etc.).

The result: agents frequently generate code that compiles but violates local conventions, ignores version-specific changes, or hits subtle “footguns”. Developers end up copy-pasting docs and re-explaining best practices to the agent on every new task.

Proposal: package-level context files as integration guides

Idea: extend the AGENTS.md ecosystem with a second, optional convention:

A small, AI-focused package-level context file(e.g. CONTEXT.md) that ships with an SDK/library and explains how to use it correctly for the installed version.

This file would live in the package itself (e.g. library root) and be consumed by any IDE/agent/CLI that supports the AGENTS.md spec and this extension.

Typical content should be not marketing or general documentation; it’s agent-facing operational knowledge for that package in that version.

Why this belongs in the AGENTS.md ecosystem

The AGENTS.md spec already defines a standard for project-level instructions that tools can implement once and support everywhere.

A package-level context file would be the natural counterpart:

• Same philosophy, different scope

  • AGENTS.md → “Here’s how to behave in this repo.”
  • Package-level context file → “Here’s how to use this SDK/library correctly.”

• Version-local by design

  • Since the context file ships with the package, tools can be confident it describes the exact version being used, closing the gap between model training cutoff and reality.

• Tool-agnostic and reusable

  • SDK authors and platform teams can write this file once, and it becomes consumable by any AI IDE, agent framework, or CLI that implements the AGENTS.md spec and its extensions.

• Minimal overhead for integrators

  • No extra configuration for end users: install a package, and any AGENTS-aware tool can automatically leverage its context file to provide more accurate, intent-aligned suggestions.

Context file template

# <Package Name> context

## Version
- Version this file describes, and any key breaking changes.

## Mental model
- How to think about this SDK and its main abstractions.

## Core concepts
- Main public components/classes/modules and how they relate.

## Common tasks
- Typical tasks and which APIs/patterns to use for each.

## Do / Don’t
- ✅ Recommended patterns.
- ❌ Internal APIs, anti-patterns, and things the agent should avoid.

## Examples
- A few short, idiomatic snippets showing preferred usage.

[DimaKH]

I’m already experimenting with this idea in a public SDK I’m working on. You can see a real example here.

Right now my workaround has two main problems:

• Manual copy-paste: The SDK user has to manually copy the file (or its contents) into their project for the Agent to use it.

• Naming / priority issues with AGENTS.md : If the user drops my AGENTS.md into the folder where they’re integrating the SDK, IDE will treat it as the closest AGENTS file and apply those instructions to that work, even though they’re really SDK-specific, not project-level. If I keep AGENTS.md inside the SDK folder, then my AI agents use it during SDK development – but in that context I also need other instructions (test rules, commit rules, etc.), so it doesn’t really fit.