Playbooks

Playbooks are reusable local instruction packs in the Agent Skills folder format. A teammate sees a short description, then loads the full instructions only when the current task calls for them.

What a playbook is#

A playbook teaches teammates how to approach a recurring kind of work: how to prepare an account brief, apply an editorial standard, triage an incident, or follow an internal checklist. It lives under ~/Documents/Zimac/playbooks/<id>/ and remains under your local file control.

A playbook does not grant a tool, run code, or prove that its process is correct. Its instructions influence model behavior after the model chooses to load them. Use a plugin for a sandboxed executable extension, or Workflows for scheduled and approval-gated automation.

Folder format#

The required file is SKILL.md. It begins with YAML frontmatter containing a name and a description, followed by Markdown instructions:

The description matters twice: it explains the playbook in the panel and tells the model when the playbook is relevant. Make it specific about the task and trigger, while putting the detailed procedure in the body.

Create & edit#

1. 1
   Select New playbook.

   Enter a name, a task-focused description, and the instruction body. Zimac creates the folder and SKILL.md.

2. 2
   Review the generated file.

   New playbooks arrive disabled. Use Open folder to inspect or edit the Markdown in your editor.

3. 3
   Refresh after file edits.

   The panel rescans the playbooks directory and reports validation problems or changes.

4. 4
   Enable the reviewed version.

   Enable only after the text and bundled files say exactly what you intend teammates to follow.

The panel currently creates, lists, enables, disables, opens, refreshes, and deletes playbooks. It does not provide an in-panel Markdown editor or rendered preview; edit an existing playbook in its folder.

Enable & drift#

Enabling records a hash of the complete playbook folder, not just the visible instructions. Only an enabled playbook whose current folder hash still matches that approval is available to teammates.

If SKILL.md or a bundled reference changes, the playbook is marked changed and deactivated. This prevents an edited instruction pack from inheriting approval granted to earlier bytes. Refresh, inspect the new contents, and enable it again.

How teammates load it#

Zimac uses progressive disclosure. The model’s playbook shelf contains only names and one-line descriptions for enabled, unchanged playbooks, with at most 30 entries exposed. The full Markdown body is not placed into every prompt.

When a description matches the current task, the teammate can call the playbook tool to load its body. This reduces unrelated prompt context, but selection remains a model decision. Name the playbook in your request when you want it used explicitly.

Bundled references#

A playbook folder can include supporting text files such as examples, policies, or checklists. The playbook can ask the teammate to load one when needed. Reference reads are contained to the playbook folder, limited to text content, and capped at 128 KB per file.

Reference content is returned in a fenced block and labeled as untrusted data. That boundary helps distinguish source material from instructions, but you should still inspect files for secrets or hostile content before bundling them. The loaded instruction body is capped at 64 KB and sensitive-looking values are redacted during loading.

Manage & limits#

• Disable keeps the folder but removes the playbook from the model shelf.
• Refresh discovers file changes and new folders; it does not silently approve changed content.
• Delete removes the local playbook folder and its persisted state. This is destructive—copy the folder elsewhere first if you may need it.
• Only enabled, valid, unchanged playbooks can be loaded. Descriptions beyond the 30-entry prompt shelf are not promised to be discoverable by the model.
• Playbooks do not provide deterministic execution, test their own claims, grant new permissions, or bypass approval requirements attached to tools and workflows.
• Playbooks are local files, not a team-sync or publishing system.