SKILL.md Anatomy

A promoted skill lives at ~/.ptah/skills/<slug>/SKILL.md and has the same shape as any hand-authored skill — frontmatter plus prose. There is no second file format for auto-synthesized skills: the frontmatter generator writes exactly the shape Ptah’s plugin-discovery loader already expects, on purpose, so a synthesized skill and a hand-written one are indistinguishable at load time.

Layout

---
name: api-error-triage
description: Triage failing HTTP calls — read the failing request, check the
  server log, propose a fix. Use when the user reports a 4xx/5xx from a backend
  endpoint or asks "why is this API call failing?".
when_to_use: 'The user reports a failing HTTP call or asks why a request is erroring.'
---

# API Error Triage

## Step 1: Identify the failing call

...

Frontmatter fields

Field	Purpose
`name`	Slug used by the agent loader; matches the directory name
`description`	Trigger text the orchestrator uses to decide when to invoke the skill
`when_to_use`	Optional. Extracted from a `## When to use` section in the drafted body, if one exists

That’s the whole file. It is deliberately minimal.

Runtime consumption

Once written, the file is loaded by Ptah’s skill engine on the next session. There is no second mechanism for auto-skills — they participate in the same discovery, junctioning, and trigger-matching as hand-authored ones.

See MCP & Skills → Skills for how skill files are loaded, junctioned into <workspace>/.claude/skills/, and matched at runtime.