# `Planck.Agent.Skill`
[🔗](https://github.com/alexdesousa/planck/blob/v0.2.2/lib/planck/agent/skill.ex#L1)

Filesystem-based agent skills.

A skill is a subdirectory under a skills directory (e.g. `.planck/skills/`)
containing a `SKILL.md` file. The file has YAML frontmatter with `name` and
`description`, followed by usage instructions, resource references, and any
other context the agent needs.

## Directory layout

    .planck/skills/
    └── n8n-expert/
        ├── SKILL.md            ← required
        ├── docs/
        │   └── node-types.md   ← lazily loaded by the agent via `read`
        └── scripts/
            └── validate.sh     ← runnable via `bash`

## SKILL.md format

    ---
    name: n8n-expert
    description: Expert at building n8n workflows and automation.
    ---

Descriptions containing colons must be quoted:

    description: "Expert at n8n: workflow automation"

    # N8N Expert

    You are an expert at n8n...

    ## Resources

    - `docs/node-types.md` — reference for all n8n node types
    - `scripts/validate.sh` — validates a workflow JSON file

Only `name` and `description` are parsed from the frontmatter. The rest of
the file is plain Markdown consumed by the agent when it loads the skill.

## Usage

    skills = Planck.Agent.Skill.load_all(["~/.planck/skills"])

    # Skills are typically threaded through AgentSpec.to_start_opts/2 via
    # skill_pool:, which resolves spec.skills names and appends the skill
    # section to system_prompt for the relevant agent.
    start_opts = Planck.Agent.AgentSpec.to_start_opts(spec, skill_pool: skills)

The agent discovers skills from the system prompt index and loads `SKILL.md`
via the `read` tool when a skill is relevant. Scripts are run via `bash`.
No special runtime support is required — skills are just files.

# `t`

```elixir
@type t() :: %Planck.Agent.Skill{
  always_present: boolean(),
  creator: String.t() | nil,
  description: String.t(),
  name: String.t(),
  path: Path.t(),
  planck_version: String.t() | nil,
  skill_file: Path.t()
}
```

A loaded skill.

- `:name` — identifier used in the system prompt index
- `:description` — one-line summary shown to the agent
- `:path` — absolute path to the skill directory
- `:skill_file` — absolute path to `SKILL.md`
- `:always_present` — when `true`, always included in the system prompt index
  regardless of usage ranking. Set by users; agents always write `false`.
- `:planck_version` — semver string set on Planck-bundled skills; `nil` on
  user- and agent-created skills. Used for upgrade detection.
- `:creator` — `"agent"` for skills written by the SkillReflector; `nil` for
  user-created skills. Used to filter the reflector's `list_skills` view so
  agents only see and manage their own skills.

# `from_file`

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

Load a single skill from a `SKILL.md` file path.

Returns `{:ok, skill}` or `{:error, reason}`.

# `list_skills_tool`

```elixir
@spec list_skills_tool([t()]) :: Planck.Agent.Tool.t()
```

Build a `list_skills` tool that returns all available skill names and descriptions.

This is an opt-in discovery tool. Add `"list_skills"` to an agent's TEAM.json
`"tools"` array when that agent needs to autonomously discover what skills exist.
Workers that receive skill names from the orchestrator do not need this tool.

# `load_all`

```elixir
@spec load_all([Path.t()]) :: [t()]
```

Load all skills from a list of directories.

Each directory is scanned for subdirectories containing a `SKILL.md` file.
Directories that do not exist are silently skipped. Invalid `SKILL.md` files
are skipped with a warning.

Paths are expanded via `Path.expand/1` so `~` and relative paths resolve
correctly.

# `load_skill_tool`

```elixir
@spec load_skill_tool([t()], keyword()) :: Planck.Agent.Tool.t()
```

Build a `load_skill` tool that loads a skill's `SKILL.md` by name.

The tool is a closure over the given skill pool. It is automatically added to
every agent when skills are available — agents do not need to declare it in
their TEAM.json `"tools"` array.

# `system_prompt_section`

```elixir
@spec system_prompt_section([t()], [String.t()], pos_integer()) :: String.t() | nil
```

Build the skill index section for the system prompt.

Accepts the full pool of available skills, the ordered list of ranked skill
names (from SQLite usage history), and the maximum number of ranked skills to
show. Returns `nil` when there are no skills at all.

## Structure

1. **Pinned** (`always_present: true`) — always included, listed first.
2. **Last used** — up to `top_n` skills from `ranked_names`, excluding pinned.
3. **Discovery line** — appended when there are more skills than shown.

---

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