@package-system

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

FolderCategoryReaches the model asUse for
rules/*.mdruleAlways-on system-prompt block, near the topHard constraints the agent must always obey (Rules)
instructions/*.mdinstructionSystem-prompt block, grouped with rulesHow-to guidance and workflows
docs/*.mddocsListed in the package overview (title + description); read on demand — not injected by defaultBackground and reference material (Docs)
skills/<name>/SKILL.mdskillAdvertised in the package overview; body rendered on activationProcedural capability bundles (Skills)
agents/*.mdagentSpawnable delegate personaSub-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.

On this page