# Agent Context
Keep reusable package guidance separate from repository-only instructions, and make both easy for agents to discover.
## Package guidance
Put guidance that benefits users of a crate in its tracked `context/` directory. Explain package-specific architecture, important invariants, common usage patterns, and decisions that are not obvious from the public API. Keep each guide focused on one topic, use descriptive lowercase filenames, and link related guides together.
Include `context/**` in the published Cargo package when downstream users need the guidance. Bake Agent Context builds `.agents/context/index.md` from each installed document's first heading and first prose sentence. It does not create or modify the repository owner's `agents.md`. Use the `bake-agent-context-usage` skill for file format, skill metadata, and installation details.
Use a skill for a task-oriented procedure that an agent should follow, such as setting up a repository or preparing a pull request. Skills are source Markdown files in `context/` with YAML front matter containing `type: skill` and a description. Bake installs them under `.agents/skills/` with names prefixed by the provider crate. Skill documents are not copied to `.agents/context/` or listed in the generated context index.
## Repository-only instructions
Put guidance that applies only to the current checkout in `.agents/`. This can include local development instructions, project-specific skills, and instructions that should not ship to crate users. Do not put credentials or machine-specific private details in package context.
The repository owner controls `agents.md`; context installation leaves it untouched. If agents should use dependency guidance, add a stable link to `.agents/context/index.md` there. `cargo bake agent:context:install` maintains a marked block in the local Git exclude file (`.git/info/exclude`) for generated `.agents/context/` files, the skill ownership registry, and each dependency-installed skill directory. These rules stay in the local checkout instead of becoming project files. Project-owned skill directories remain trackable. Edit package skill sources under `context/` and repository-only skills under `.agents/skills/`, not generated dependency copies.
## Install and update
Add `bake-agent-context` to the project's private `bake/` package, directly or through a shared task package such as `socketry-project`. Run `cargo bake agent:context:install` to install ordinary context and skills from resolved dependencies and update `.agents/context/index.md`. Run it again after changing a context-providing dependency. Use `--package CRATE` to install from one provider, or the skill-specific tasks to list and install selected skills.
Before changing a project, follow its `agents.md` instructions, read relevant installed context from `.agents/context/index.md`, and apply any skills that fit the work. For details about the available Bake tasks and their options, use the `bake-agent-context-usage` skill.