Format

Format

A skill is a folder. The required file is SKILL.md. You write the source block. python3 scripts/generate.py writes the folder. Do not hand-edit plugins/. The next generate overwrites it.

Folder

plugins/supply-chain/
├── .claude-plugin/plugin.json
└── skills/dock-photo-note/
    ├── SKILL.md
    ├── references/        optional, loaded only if needed
    ├── scripts/           optional, Python standard library only
    └── assets/            optional

plugin.json author is an object, not a string:

{ "name": "Yasir Jilani" }

No README.md inside the skill folder. No network call. Skills are not stored inside .claude-plugin/.

Name

dock-photo-note

Rules are on Naming. The folder, the name field, and examples/by-skill/supply-chain/dock-photo-note.md use that same string.

What you write

Add this block to the source pack for the domain. One skill, then a blank line.

dock-photo-note | Dock Photo Note | dock photo note
job: Record a dock photo against the PO line and the tally, without calling a short count theft.
triggers: dock photo; receiving photo; short shipment photo; OS&D photo
inputs: The PO; The tally; What the photo shows; Who took it
steps: Name the PO line. || State the counted quantity and the billed quantity. || Say only what the photo shows. || Do not call a short count theft. || Name who sends the note. || Hold the difference out of available stock.
anti: A theft claim from a short count; A photo of a different PO; Stock raised to match the bill
example: PO 5521 billed 40 filters. The tally is 32. The photo shows 32 boxes and an intact seal.
out: A note for 8 short, stock available 32, and no theft claim.
related: dock-exception-note

Field rules:

Field	How to write it
Header	name | Title | artifact
job	One sentence. What the skill produces.
triggers	At least 3, separated by semicolons
inputs	Facts the person must already have. Semicolons.
steps	At least 5. Separate steps with ||. Start each with a capital title and a colon.
anti	At least 3 failures. Semicolons.
example	The situation, in one or two sentences
out	The decision the outcome must reach
related	Existing skill names. Semicolons.

Do not put < or > in any field. Those characters break the frontmatter.

The example file still needs a scenario, sample data, and a filled outcome. A one-line out is not the example. See Examples.

What generate writes

---
name: dock-photo-note
description: "Record a dock photo against the PO line and the tally, without calling a short count theft. Use when the user mentions dock photo, receiving photo, short shipment photo, or OS&D photo, or asks for a dock photo note. Supply chain skill by Yasir Jilani."
license: MIT
compatibility: Agent Skills standard. No network access, extra packages, or credentials required.
metadata:
  author: Yasir Jilani
  version: "1.0.0"
  domain: supply-chain
---

The body, in order:

1. The job, as the opening paragraph
2. When to use this skill
3. When not to use this skill
4. Professional boundary
5. Operating boundaries
6. Inputs to collect
7. Workflow
8. Output
9. Quality bar
10. Example: scenario, example data, example outcome
11. Anti-patterns
12. Related skills

Keep SKILL.md under 500 lines. Put a long note in references/.

description is what Claude sees before it loads the skill. It must say what the skill does and when to use it. Maximum 1,024 characters.

Example file for this skill

examples/by-skill/supply-chain/dock-photo-note.md

# Dock Photo Note

`dock-photo-note`

## What this is for

Record a dock photo against the PO line and the tally, without calling a short count theft.

## Scenario

Diane Cho at Harbor Goods received PO 5521 on 14 September 2026. The bill says 40 filters. The tally is 32. The photo shows 32 boxes and an intact seal.

## Example data

PO: 5521
Billed: 40 of SKU 1044
Tally: 32
Photo: 32 boxes, seal intact, no other SKU in frame
Photographer: dock lead, 14 Sep 2026

## Example outcome

**Dock photo note — PO 5521**

Short 8. Available stock from this receipt: 32, not 40.
The photo matches the tally. The intact seal is not a theft finding.
Do not raise stock to 40 while the 8 are open.

After the edit

python3 scripts/generate.py
python3 scripts/validate.py
python3 scripts/install.py --tool claude --domain supply-chain --dry-run

The diff must include source/, the new SKILL.md, and the example file. A hand-edited SKILL.md with no source change is not a complete change.