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))

Size Limits

• Peer skills sit at 8-14k chars. Aim for that range.
• If pushing past 20k, split into references/*.md and reference them from SKILL.md.

Writing Quality Principles

A skill exists to make the agent's process more predictable. Predictability does not mean identical output every run; it means the agent reliably follows the same useful discipline.

1. Optimize for process predictability. Ask: what behavior should change when this skill loads? If a line does not change behavior, cut it.
2. Choose the right context load. A model-invoked skill pays for its description every turn. Keep descriptions focused on trigger classes and the skill's distinctive behavior. Put details in the body or linked references.
3. Use an information hierarchy. Put always-needed steps in SKILL.md; put branch-specific or bulky reference material in references/, templates/, or scripts/ and point to it only when needed.
4. End steps with completion criteria. Each ordered step should say how the agent knows it is done. Good criteria are checkable: "every modified file accounted for" beats "summarize changes."
5. Co-locate rules with the concept they govern. Avoid scattering one idea across the file.
6. Use strong leading words. Prefer compact concepts the model already knows — "tight loop," "tracer bullet," "root cause," "regression test" — over long repeated explanations.
7. Prune duplication and no-ops. Keep each meaning in one source of truth. If a sentence doesn't change agent behavior vs the default, delete it.
8. Watch for premature completion. If agents tend to rush a step, sharpen that step's completion criterion.

Common quality failures:

• Premature completion — skill lets the agent move on before work is done
• Duplication — same rule in multiple places, drifts
• Sediment — stale lines remain because adding felt safer than deleting
• Sprawl — too much always-visible material; push branch-specific behind pointers
• No-op prose — generic advice the agent would follow without the skill

Tool Reference Rules

Tools referenced in SKILL.md prose must be native Poirot tools (listed in allowed-tools) or MCP servers the skill explicitly expects. Do NOT name shell utilities the agent already has wrapped:

• grep → bash (run grep via bash)
• cat/head/tail → read_file
• sed/awk → str_replace
• find/ls → list_dir

Peer-Matched Structure

# <Title>

## Overview
One or two paragraphs: what and why.

## When to Use
- Bulleted triggers
- "Don't use for:" counter-triggers

## <Topic sections specific to the skill>
- Quick-reference tables are common
- Code blocks with exact commands

## Common Pitfalls
Numbered list of mistakes and their fixes.

## Verification Checklist
- [ ] Checkbox list of post-action verifications

Not every section is mandatory, but Overview + When to Use + actionable body + pitfalls are the minimum.

Directory Placement

builtin_skills/<category>/<skill-name>/SKILL.md     # builtin
skills/<skill-name>/SKILL.md                         # user-local

Builtin categories: core, research, software-development, creative, productivity. Pick the closest existing category. Don't invent new top-level categories casually.