Instructions
instructions[] — markdown guidance a package injects into the system prompt, and how every prompt-injected file is rendered, capped and gated.
Beyond tools and skills, a
package contributes plain markdown that shapes agent behavior. Five markdown
categories become typed arrays on the package definition — skills,
instructions, rules, agents, docs — plus team
members. Each file lives in its category folder, needs a frontmatter name (or
id) to be discovered, and takes its category from the folder, never from
frontmatter (see the directory contract).
Category cheat-sheet
| Folder | Category | Reaches the model as | Use for |
|---|---|---|---|
rules/*.md | rule | Always-on system-prompt block, near the top | Hard constraints the agent must always obey (Rules) |
instructions/*.md | instruction | System-prompt block, grouped with rules | How-to guidance and workflows |
docs/*.md | docs | Listed in the package overview (title + description); read on demand — not injected by default | Background and reference material (Docs) |
skills/<name>/SKILL.md | skill | Advertised in the package overview; body rendered on activation | Procedural capability bundles (Skills) |
agents/*.md | agent | Spawnable delegate persona | Sub-agent identities (Agents) |
Workflow templates and declared sources are typed JSON arrays, not markdown categories, and are never injected: see Workflows and Sources.
Prompt-injected categories
Rules and instructions are injected into the system prompt for every turn, each
wrapped in a <package_file> block that carries its category, id, owning
package and title:
<package_file category="rule" id="mutation-safety" package="brain-core" title="Mutation safety">
...the file body, without its frontmatter...
</package_file>The frontmatter is dropped when every key in it is one the platform renders
itself (id, name, title, description, activation, requiredFeatures,
defaultEnabled, overwrite). Any other key keeps the whole file, frontmatter
included — an imported rule's scope (paths, applyTo, globs) still reaches
the model that way. A file the prompt already carries is named in the package
overview without repeating its description.
They render near the top of the prompt (primacy). Within each group, files sort
by category priority and path; each file's content is capped at injection time
by the packageFileMaxChars platform setting (default 8,000 characters,
admin-tunable). Flat {{conversationId}}, {{agentId}}, {{projectId}}, and
{{userId}} placeholders substitute at injection; dotted forms such as
{{user.name}} ship literally and should not be used.
Because injected files cost tokens on every turn, keep rules and
instructions tight, push long reference into docs (read on demand), and put
procedural detail into a skill body — a skill renders only on activation.
Visibility
Every category obeys the same two gates, deny-by-default:
- Package state — a disabled package's contributions are not injected, not advertised, and not listed.
- Caller grants — a contribution may declare
requiredFeatures: [a, b]in frontmatter (flat flow array). A caller missing any listed feature never sees it: not in the prompt, not in the package overview, not in the files catalog. Hidden means hidden — gated contributions are never rendered as locked or off, so non-holders cannot infer they exist.
The predicate and grant model are described in Features.
Within those gates, every file contribution of every package is also individually toggleable at two scopes: agent scope in the packages editor, and conversation scope in the composer's package selector, where every package row expands into per-file rows (opt-in files badged). An agent-level per-file off is final — a conversation cannot re-enable it.
Source-contributed files
A synced filesystem source can contribute the same five categories with no
package.json: a mounted repository's .claude/ or .cursor/ folder, a
directory of skills/ and rules/, or a free-standing SKILL.md folder
groups into a source package with deliberate defaults (source rules and
identity files are opt-in, docs are never auto-injected). Layouts, grouping,
defaults and the full precedence chain: Source packages.