Authoring skills

A skill is a Markdown reference page the AI loads on demand. Capture your team's playbook once, and HISAB pulls it in when it's relevant.

What a skill is

A HISAB skill is not a program. It is a single Markdown file containing guidance — conventions, procedures, formats, gotchas — that the AI reads as extra context for a task. Skills do not run; they teach. When the AI needs to do something (build a report, reconcile, write a formula) it uses the regular MCP tools, and a skill simply tells it how you want that done.

Each skill is one .md file in your per-user skills folder:

%APPDATA%\HISAB\Skills\
├── monthly-bank-rec.md
├── dcf-valuation.md
└── house-style.md

The file name (stem) is the skill's identifier. The folder is created for you on first launch and seeded with HISAB's built-in skills.

File format

A skill is optional YAML frontmatter (between --- fences) followed by a Markdown body. The body is what the AI reads; the frontmatter is metadata.

---
name: Monthly bank reconciliation
description: How we match a bank statement against the bank book.
triggers: [reconcile, bank rec, statement match]
slash: bankrec
---

# Monthly bank reconciliation

Match the bank statement against the bank book by amount and date.

## Procedure
1. Read both sheets with `read_range`.
2. Match rows where amounts are equal and dates are within
   2 days. Treat anything unmatched as an exception.
3. Write a "Mismatches" sheet listing the exceptions.
4. Draft a journal entry for the net difference, but do not
   post it without my approval.

## House rules
- Amounts in parentheses for negatives.
- Never overwrite the source sheets.

If you omit the frontmatter entirely, the file still works — HISAB uses the file name as the skill name and the whole file as the body.

Frontmatter fields

• name — display label shown in the Skills tab. Defaults to the file name.
• description — one-line summary. Shown under the title in the list, and returned by list_skills so the AI can decide whether the skill is worth loading.
• triggers — optional comma-separated keywords (with or without [ ] brackets). Searchable hints; they help the skill surface in the catalogue.
• slash — optional shortcut. Setting slash: bankrec lets you type /bankrec in the chat box to pull the skill in directly.
• always_on — set always_on: true to inject the body into every prompt instead of loading it on demand. Reserve this for short, universal house rules — long always-on skills burn tokens on every turn.

Create a skill from the panel

You don't have to touch the folder by hand. Open the Skills tab in the HISAB panel and click + New skill. The editor has fields for Name, Description, an Always-on checkbox, and a Body text area (Markdown). Save writes the .md file for you with the correct frontmatter.

• Edit / Delete buttons on each skill let you revise or remove your own skills.
• The search box narrows the list by name, file stem, or description.
• Refresh re-reads the folder if you edited files outside the panel.

HISAB's own built-in skills are hidden from this list so you can't accidentally delete one the add-in depends on. The list shows only the skills you've added.

How the AI finds your skill

The AI discovers skills with two tools: list_skills returns the catalogue (name + description + size), and read_skill loads one skill's full body by its stem, name, or slash. Skills are treated as guidance, not hard rules — they describe the best-practice procedure for a task, and the AI still owns the turn. A clear, specific description is the single biggest factor in whether the AI picks the right skill.

If you need Python

Skills are reference text, not Python entry points — there is no main.py and no import hisab API. When a task needs real computation, the AI writes Python and runs it in HISAB's bundled, isolated sandbox at run time. Your skill's job is to describe the approach (which sheets, what tolerances, what the output should look like); HISAB generates and executes the code. See Running Python for how the sandbox works.

Sharing skills

Because a skill is just a Markdown file, sharing is a file copy: send the .md to a teammate and have them drop it into their %APPDATA%\HISAB\Skills\ folder (or paste the body into + New skill). Keep your skills in a shared folder or Git repo to version-control your team's playbook over time.