skill-authoring

Authoring Poirot Skills

Overview

A SKILL.md can live in two places:

1. Builtin (in-repo): poirot/backend/agents/skill/builtin_skills/<category>/<name>/SKILL.md — committed, shipped with the package. Use write_file + git add.
2. User-local: skills/<name>/SKILL.md — personal, gitignored. Created via /skill install <path> or by writing directly.

This skill covers authoring for both, with emphasis on builtin skills.

When to Use

• User asks you to add a skill "in this repo / commit"
• You're committing a reusable workflow that should ship with Poirot
• You're editing an existing skill under builtin_skills/

Required Frontmatter

Source of truth: poirot/backend/agents/skill/parser.py::parse_skill_file. Hard requirements:

• Starts with --- as the first bytes (no leading blank line).
• Closes with \n---\n before the body.
• Parses as a YAML mapping.
• name field present (lowercase, hyphens).
• description field present.

Peer-matched shape:

---
name: my-skill-name               # lowercase, hyphens
description: Use when <trigger>. <one-line behavior>.
allowed-tools:                    # Poirot tools this skill may invoke
  - bash
  - read_file
  - write_file
  - list_dir
  - str_replace
  - web_search
  - browse_page
  - present_files
  - read_snapshot
enabled: true
related-skills: [other-skill]     # optional cross-references
license: MIT                      # recommended for contributed skills
author: <human contributor or source attribution>
---

allowed-tools / enabled / related-skills / license / author are NOT enforced by the parser (it reads name/description/allowed-tools/enabled), but every peer has them — omit and your skill sticks out.

Description Standard

description ≤ 60 characters, one sentence, ends with a period. State the capability, not the implementation. No marketing words ("powerful", "comprehensive", "seamless"). Don't repeat the skill name.

Verify:

import re, pathlib
m = re.search(r'^description: (.*)$',
              pathlib.Path('builtin_skills/<cat>/<name>/SKILL.md').read_text(),
              re.MULTILINE)
assert len(m.group(1)) <= 60, len(m.group(1))