Why you keep explaining the same thing

You have had a few conversations by now. One limitation shows up fast: every new Session starts with nothing. Two ordinary requests, and the questions that come back:

Re-typing that background costs time and input tokens on every request. It also makes results wobble: the day you forget to mention that the top shelf is the freezer, you get a different answer.

A procedure, written down once

A Skill stores that background in a file. At the start of a new Session, Pi Agent offers the model a short summary of each installed Skill; when a request matches one, the model reads the full procedure instead of asking you for it.

Four things make a Skill work like that card:

• It sits in a known place. Under /data/pi-agent/skills/, which is where Pi Agent looks.
• It has a name and a summary. The name and description fields at the top of SKILL.md.
• The detail stays folded up. The model gets the summary first and reads the full instructions only when a request needs them.
• You install it once. Every new Session gets it, without you doing anything.

Guidance, not a program that runs

A Skill looks like an app or a HACS integration because all three extend what a system can do. It works in a fundamentally different way, and that difference matters for security.

One folder each, one file that matters

Pi Agent keeps Skills in one fixed location: /data/pi-agent/skills/. Each Skill gets its own folder, and each folder must contain a SKILL.md. A folder without that file is skipped.

flowchart TD
  R["/data/pi-agent/skills/"] --> A["fridge-check/"]
  R --> B["ha-automation-templates/"]
  R --> C["video-pitch/"]
  A --> A1["SKILL.md - required"]
  A --> A2["examples/ - optional"]
  B --> B1["SKILL.md - required"]
  B --> B2["motion-light.yaml - optional"]
  C --> C1["SKILL.md - required"]
  C --> C2["scene-templates/ - optional"]

Two notes about that path. Inside the container, the ~/.pi/agent/skills symbolic link points at the same place, so the command line and the interface work on the same files. And Home Assistant full backups include add-on /data/ by default, so your Skills come back with a restore. The 720MB video-tools cache is deliberately excluded and handled separately.

You would normally manage all this through the Skills tab in Settings rather than the directory. With nothing installed yet, it looks like this.

The Skills tab in SettingsNothing installed yet. Nothing is broken either — there is simply no procedure stored.

• Skills is one of the five tabs across the top of the dialog, sitting between Models and Sub-agents. That is where this lives.
• No skills found in the left column is the normal state until you install one. Pi Agent works perfectly well with none.
• + Add skill sits at the foot of that same column. Part 10 covers what happens after you press it.
• Select a skill is the placeholder in the right-hand pane. That pane is where a Skill's detail appears once the left column has something in it.

The model never looks in your folders

This part explains nearly every “why is it ignoring my Skill” problem later. The model on the far end cannot see your disk. Pi Agent does the looking, then tells it what is there.

1. Step 1

   Pi Agent scans the folder

   The pi-web backend reads every */SKILL.md under /data/pi-agent/skills/ and pulls the name and description out of the YAML frontmatter at the top. This usually happens when you select “New conversation”; some versions also refresh on “Reload Skills”.

2. Step 2

   Those names and summaries go into the system prompt

   The list joins the instructions that start the Session. The wrapper varies by Pi Agent and pi-coding-agent version — <available_skills>, <skills>, or a Markdown section. The payload is the same either way: names and descriptions, nothing more.

3. Step 3

   The model decides whether one applies

   Ask about a refrigerator photo and it can match that to fridge-check, then read the whole file and follow it. Ask about something unrelated and it ignores the list.

Here is roughly what the menu looks like:

That block is the model's entire view of your Skills until it opens one. So the description does all the work of getting a Skill noticed.

Seeing the list for yourself

You do not have to take this on trust. The System button in the top toolbar opens the System prompt panel, which shows the instructions the Session started with.

The System prompt panelEverything the model was told before you typed anything.

• “You are an expert coding assistant operating inside pi” opens the text. This is the real instruction the model received — if a Skill is not named in here, the model does not know it exists.
• Available tools lists four, one line each: read, bash, edit and write. The line under the list adds that a project may give the model other custom tools on top of these.
• Guidelines follows, with house rules such as using bash for file operations and read rather than cat to examine a file.
• The text runs on below the visible edge. Scroll it for the rest of the Guidelines and, once you have Skills installed, the section that lists them.

It is also the fastest way to confirm a newly installed Skill reached this Session: open the panel, scroll down to the Skills section, and look for the name. That section's label and appearance vary by Pi Agent version, so go by the name and description rather than the heading. The panel above was taken on a machine with no Skills installed, which is why the visible text runs from the tools straight on to the guidelines with no Skills section in between.

No Skills section at all means either nothing is installed, so Pi Agent leaves it out, or your pi-web version is too old to show it separately and needs an upgrade.

One file, and no code inside it

In practice most Skills land in one of five areas: household routines such as waste sorting and refrigerator inventories; Home Assistant automation templates like motion lights and arrival climate control; video production with a fixed format; data processing over CSVs, logs and receipts; and external tools such as Notion, Google Calendar or a Telegram bot.

The file itself is smaller than people expect. A usable fridge-check Skill needs exactly one file, at /data/pi-agent/skills/fridge-check/SKILL.md. It begins like this:

The part between the three hyphens is the frontmatter — the only bit Pi Agent parses. Everything below is ordinary Markdown: the procedure, the limits, the output you want. No code anywhere, and none needed.

Four things that actually go wrong

Where to go from here