Planck.Agent.Skill (Planck.Agent v0.1.8)

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.

Summary

Types

t()

A loaded skill.

Functions

from_file(skill_file)

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

list_skills_tool(skills)

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

load_all(dirs)

Load all skills from a list of directories.

load_skill_tool(skills, opts \\ [])

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

system_prompt_section(all_skills, ranked_names, top_n)

Build the skill index section for the system prompt.

Types

t()

@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.

Functions

from_file(skill_file)

@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(skills)

@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(dirs)

@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(skills, opts \\ [])

@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(all_skills, ranked_names, top_n)

@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

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