Instructions

Instructions are the plugin's standing behavior: rules, scope, conventions, and constraints that should apply throughout a session.

Add an instruction file

The smallest Soubi plugin is an AGENTS.md:

# Plugin instructions

Review changes for correctness, security, and maintainability. Report findings with file paths and concrete evidence.

Soubi checks instruction files in this order and uses the first one it finds:

1. AGENTS.md
2. CLAUDE.md
3. GEMINI.md
4. instructions.md

Use one canonical file when possible. The adapter decides which native filename or manifest field receives the content.

Keep instructions stable

Put behavior here when it should always be present:

• the plugin's role and boundaries
• repository-wide rules
• required output structure
• safety constraints
• verification expectations

Situational procedures belong in Skills, where a harness can load them only when needed. User-invoked workflows belong in Commands.

Pass through frontmatter

Instruction frontmatter is preserved on the portable instruction document and emitted where the target supports it:

---
audience: maintainers
---

# Plugin instructions

Prefer focused changes and preserve existing public APIs.

Unknown fields are not rejected by Soubi. Whether a field affects behavior depends on the target harness.

Check the emitted form

Run a targeted build and inspect the native artifact:

npx soubi build . --harness claude,codex

Use Adapters to find the destination path for each harness.