# `Agentic.Skill.Parser`

Parses SKILL.md files with YAML frontmatter and markdown body.

The expected format is:

    ---
    name: my-skill
    description: What the skill does and when to use it
    ---

    # Detailed instructions
    ...

Required frontmatter fields: `name`, `description`.
Optional: `license`, `metadata` (map), `compatibility`, `type`, `core`,
`loading`, `version`, `parameters`, `model_tier`, `source`.

## Skill Types

- `"skill"` (default) — freeform instructions
- `"sop"` — structured workflow with steps, constraints, and success criteria

## Loading Modes

- `"on_demand"` (default) — listed by name, loaded via `skill_read` when needed
- `"always"` — full body included in system prompt
- `"trigger:<event>"` — loaded when a specific event occurs (e.g. `"trigger:onboarding"`)

# `model_tier`

```elixir
@type model_tier() :: :primary | :lightweight | :any
```

# `parameter`

```elixir
@type parameter() :: %{
  name: String.t(),
  required: boolean(),
  default: String.t() | nil,
  description: String.t()
}
```

# `parsed_skill`

```elixir
@type parsed_skill() :: %{meta: skill_meta(), body: String.t(), raw: String.t()}
```

# `skill_meta`

```elixir
@type skill_meta() :: %{
  name: String.t(),
  description: String.t(),
  license: String.t() | nil,
  compatibility: String.t() | nil,
  metadata: map(),
  type: String.t(),
  core: boolean(),
  loading: String.t(),
  version: String.t() | nil,
  parameters: [parameter()],
  model_tier: model_tier(),
  source: String.t() | nil
}
```

# `parse`

```elixir
@spec parse(String.t()) :: {:ok, parsed_skill()} | {:error, String.t()}
```

Parse SKILL.md content string.

# `parse_file`

```elixir
@spec parse_file(String.t()) :: {:ok, parsed_skill()} | {:error, String.t()}
```

Read and parse a SKILL.md file from disk.

---

*Consult [api-reference.md](api-reference.md) for complete listing*