Writing a skill or team for the library

Murage ships two libraries in its repository: a skill library of more than 2,000 skills, and a team library of ready-made team packages. Both are read from disk, so the app works fully offline. This page is for adding to them through a pull request.

To write a skill or team just for yourself or your staff, you don't need any of this: see Writing your own skills and Team packages.

The skill library#

Library skills live in skills-library/, one folder per skill:

skills-library/
  weekly-client-report/
    SKILL.md
    manifest.json

SKILL.md#

The same format as any Murage skill: YAML frontmatter between --- lines, then Markdown instructions. Library skills use these frontmatter fields:

---
name: weekly-client-report
description: |
  Writes the Friday client status report from this week's notes and tasks.
  Use when asked for a client update, weekly report or status email.
  Do NOT use for invoices or internal team updates.
license: Apache-2.0
metadata:
  author: your-name
  version: "1.0.0"
  tags: "reporting clients writing"
  category: "operations"
  subcategory: "client-services"
  difficulty: "beginner"
---

name must be lowercase letters and numbers with single hyphens, up to 64 characters, and match the folder name. The description (up to 1,024 characters) is what a bot sees in its skill index, so say what the skill does, when to use it and when not to.

manifest.json#

Each library skill also has a manifest the app reads when it loads the library:

{
  "id": "weekly-client-report",
  "name": "Weekly Client Report",
  "version": "1.0.0",
  "description": "Writes the Friday client status report...",
  "defaultEnabled": false,
  "triggerTerms": ["reporting", "clients", "writing"],
  "requiredCapabilities": []
}

The loader is strict. It refuses a manifest when:

• id isn't a valid id or doesn't match the folder name;
• name or description is missing;
• version isn't three numbers, such as 1.0.0;
• defaultEnabled isn't a true or false value;
• triggerTerms is empty;
• requiredCapabilities isn't a list.

An optional attachedTo field only accepts workspace-chief, for skills meant for the Chief of Staff.

Skill Guard and the library

Library skills are scanned by Skill Guard like any other. The recorded results are in skills-library/scan-verdicts.json. A new library skill should come back clean. If it's flagged, rewrite the flagged lines rather than asking for an exception: people see the verdict before they switch a skill on.

What makes a good library skill

• One job, done well, in a page or two.
• Numbered steps and a clear definition of done.
• No secrets, no network calls to outside sites, no instructions to skip approvals or ignore rules.
• Written for any business, not one company's internal names.

The team library

Team packages live in library/packages/, one murage.package file per team (JSON, or Markdown for some imported teams). Single-bot profiles live in library/assistants/. The format is described field by field in Team packages.

Library package conventions:

• id is a lowercase slug; release is a three-number version.
• author names who wrote it; license is Apache-2.0 for library packages.
• Every bot's skills should name skills that exist in skills-library/. The catalog counts only skills the library actually ships, so the number a card shows is the number that installs.
• routines must have enabledAfterInstall: false.
• requirements.apps should list every connected app the team really needs, each with a reason, so people know before they import.

The catalog

The team library the app shows is built from a local catalog, library/catalog.json, generated from the package files, the assistant profiles and the skill library. After adding or changing a package:

pnpm catalog:build   # regenerate library/catalog.json
pnpm catalog:check   # confirm it matches (also part of pnpm test)

Commit the regenerated catalog with your change.

Proposing your addition

1. Open an issue describing the skill or team and who it's for.
2. Add the files, run pnpm catalog:build if you changed a team, then pnpm typecheck and pnpm test.
3. Open a pull request with one skill or one team per PR.

See Contributing for the ground rules and the CLA.