Skill packages

Package skills use the Anthropic-compatible skill format: a folder of text files built around a SKILL.md. Harriet stores the files, deploys them to devices as skill zips, and can keep them in sync with a GitHub repository.

The SKILL.md format

A package is built around a SKILL.md file at the root. It starts with YAML front matter carrying name and description, followed by Markdown instructions the model follows when the skill is loaded:

---
name: expense-reports
description: Prepare a monthly expense report from receipts.
---

# Expense reports

1. Collect receipts from ...

Optional files sit beside it — for example references/… for checklists and examples, or small scripts. Keep everything UTF-8 text, and treat the package as instructions, not secrets: never embed API keys or private customer data in files you intend to share.

If a package skill has no SKILL.md file yet, its fallback instructions (the skill's prompt text) are treated as the skill content instead. The two are mutually exclusive: the editor prevents adding a SKILL.md while prompt text is set, and disables prompt text once a package file exists.

Managing files in the Anthropic package tab

The Anthropic package tab of the skill editor lists every file in the package. You can edit files in place, add a new one with Add file (enter a path such as SKILL.md), and export the whole package with Download zip.

To import a package wholesale, choose a .zip and select Import zip (replace). The archive must contain UTF-8 text members, and existing package files are replaced by the archive contents.

Syncing from GitHub

Instead of uploading files, you can point the skill at a GitHub repository. Harriet accepts three URL shapes:

• A github.com tree URL: a folder containing SKILL.md, e.g. https://github.com/org/repo/tree/main/path/to/skill
• A github.com blob URL: a single SKILL.md or skill.md file
• A raw.githubusercontent.com URL: one raw file, or a bare raw.githubusercontent.com/<owner>/<repo>/<ref> URL when SKILL.md lives at the repository root

The ref segment in the URL is the branch or tag Harriet follows until you change the URL. For private repositories, either use Pick repo to choose a repository granted to the Harriet GitHub App, or include credentials in the URL (e.g. https://x-access-token:TOKEN@github.com/…).

Two checkboxes control the sync: Replace existing package files with this sync, and Keep this skill updated from this URL (scheduled sync). With scheduled sync on, Harriet re-pulls the files on its regular integration sync, and package files become read-only in the editor; turn off scheduled sync to edit them by hand. Save sync settings stores your choices, and the tab shows the last sync time and any sync error.

How the model reads the package

Every skill served through Harriet's MCP proxy gets an automatically appended usage_guide tool. When the model needs the skill's instructions, it calls usage_guide and receives the SKILL.md (or the prompt text, when that is the content) plus access to the other bundle files, so instructions load on demand rather than crowding every conversation. On Claude Desktop, a package skill with no connector attached is provisioned as a guide-only Harriet MCP server whose only tool is usage_guide. Harriet Desktop instead receives the package as an on-disk skill zip.

Updating a package

Edit files in the Anthropic package tab, import a fresh zip, or let scheduled GitHub sync pull changes. On an approved skill, hand edits follow the usual choice between Save changes (live) and Propose update for review — see Review workflow.