# Instructions (https://docs.neuralisapp.com/package-system/instructions)

Beyond [tools](https://docs.neuralisapp.com/package-system/tools.md) and [skills](https://docs.neuralisapp.com/package-system/skills.md), 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](https://docs.neuralisapp.com/package-system/team.md)
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](https://docs.neuralisapp.com/package-system/directory-contract.md)).

## Category cheat-sheet [#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](https://docs.neuralisapp.com/package-system/rules.md)) |
| `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](https://docs.neuralisapp.com/package-system/docs.md)) |
| `skills/<name>/SKILL.md` | `skill` | Advertised in the package overview; body rendered on activation | Procedural capability bundles ([Skills](https://docs.neuralisapp.com/package-system/skills.md)) |
| `agents/*.md` | `agent` | Spawnable delegate persona | Sub-agent identities ([Agents](https://docs.neuralisapp.com/package-system/agents.md)) |

Workflow templates and declared sources are typed JSON arrays, not markdown
categories, and are never injected: see [Workflows](https://docs.neuralisapp.com/package-system/workflows.md)
and [Sources](https://docs.neuralisapp.com/package-system/sources.md).

## Prompt-injected categories [#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:

```text
<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 [#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](https://docs.neuralisapp.com/package-system/features.md).

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 [#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](https://docs.neuralisapp.com/package-system/source-packages.md).
