Agent Context

Give every agent your own procedures, skills, and scripts, for you, your company, or a Book.

Agent context is what your agents know about how you work: your procedures, your skills, and the scripts that go with them. Write it once, and all your agents follow it:

Bkper Agent
Bkper CLI Agent
Bkper for Slack
Apps built on Bkper’s agent

What you might teach them:

Your company: how reports are laid out, how Accounts are named, who approves what.
You: how you like answers, the checks you run every month.
A Book: what its Accounts mean, its month-end close, the quirks of its bank exports.

Three places

Agent context lives in three places. Each one reaches different people:

Place	Use it for	Who uses it	Who can change it
Company	How everyone at your company works	Everyone in your company domain	Your company domain’s admin
You	How you work	Only you, in all your agents	You
A Book	How to work on that Book	Everyone who can view the Book	The Book’s Owners and Editors

Who can view a Book: Owners, Editors, and people with Record and View or View Only access. Record Only users do not use a Book’s context.
Without a company domain, such as a Gmail account, there is no Company place.

When all three apply, the agent reads your company’s first, then yours, then the Book’s. The most specific comes last, so a Book’s procedure can add to your own.

What goes in it

Each place holds two kinds of guidance. Both follow open standards, so the same files work with other agents too.

Instructions

One file, AGENTS.md, that the agent reads at the start of every session. Keep it to what should always apply:

# Acme Operating Book

- Amounts are in EUR. Card fees go to Bank Fees, never to Other Expenses.
- Close a month only after its bank Accounts are reconciled.
- Ask before posting more than 20 transactions at once.

Learn more about the format at agents.md.

A skill is a procedure the agent follows when a task calls for it, such as a month-end close or a bank import. Each skill is a folder in .agents/skills, with a SKILL.md that starts with its name and when to use it:

---
name: month-end-close
description: Close a month in this Book. Use when asked to close, review, or check a month before closing.
---

1. List the month's drafts and ask what to do with each.
2. Run `check-balances.mjs` from this folder for every bank Account, and compare each with its statement.
3. Report the differences. Post nothing without asking.

The agent sees every skill’s name and description, and reads the rest only when a task matches. Write the description as “what it does, and when to use it”.
A skill can carry its own files, such as scripts, templates, or a sample export, in the same folder. The agent runs the scripts in its workspace, so the same steps give the same results every time.
The same skill name in two places: the Book’s wins over yours, and yours over your company’s.

Learn more about the format in the Agent Skills specification.

Which agents use it

Agent	Uses
Bkper Agent	Your Company’s, yours, and the Book the session started in
Bkper CLI Agent	Your Company’s and yours, and a Book’s when you start it on that Book
Bkper for Slack, and Apps built on Bkper’s agent	Your Company’s and yours, and the session’s Book when it has one

A session reads agent context when it starts. Type /reload to use what was saved since.
Other Books’ context never loads on its own. Ask the agent when you want it to read another Book’s.
A session you continue from someone else uses your own agent context, never theirs.
A bot with its own Bkper account, such as a team’s Slack bot, uses that account’s agent context, not yours.

Agent context guides the agent. It never relaxes Bkper’s rules or your permissions: the agent still acts as you, with your access only.

Add or change it

Agent context is the same set of files wherever you change it. Changes reach other people and agents only once saved, and then reach everyone in that place at once.

Ask the agent

The simplest way is to ask any of your agents, right after doing the work together:

Save how we just reconciled this account as a skill for this Book.

Add to my instructions: always show amounts with two decimals and the currency.

The agent writes the change, shows you what changed and who it will reach, and saves it when you agree.

In the Agent Workspace

In Bkper Agent, the Agent Workspace shows your Company’s, your own, and the Book’s agent context as folders: domain, user, and books. Edit the files, review what you and the agent changed, and save it. History shows who changed what, and brings back any earlier version.

On your computer

Bkper CLI, once you sign in with bkper auth login, keeps your agent context in Git folders on your computer, in ~/.bkper. Open them in any editor, such as VS Code:

Folder	Place
`~/.bkper/domain`	Your Company, when your account has a company domain
`~/.bkper/user`	You
`~/.bkper/books/<bookId>`	A Book

bkper context pull               # get or update your Company's and yours
bkper context pull -b <bookId>   # also a Book's

To save a change, commit it and git push from its folder.
Your local changes are safe. Updates never overwrite changes you have not pushed.
Bkper CLI Agent reads these folders each time it starts, and updates them in the background.
Other agents can read them too, such as a coding agent that follows AGENTS.md and .agents/skills.

Limits

Instructions: one AGENTS.md per place, up to 16,000 characters.
Skills: up to 50 per place, each SKILL.md up to 256 KB. A name uses lowercase letters, digits, and single hyphens, up to 64 characters. A description is required, up to 1,024 characters.

A skill that breaks these rules is skipped, and the Agent Workspace says why.