Start with somebody else's, even if you plan to write your own

Three reasons to install one first. No programming is required — a Skill is a folder containing a SKILL.md instruction file; the author packaged it, you supply the source and select Install. You can try one before committing time — about three minutes, against an hour of studying examples. And you get a working example: open the installed SKILL.md and read how somebody else writes one.

Skills are central to how Pi Agent is meant to be used. With the same model — GLM-4.6, say — a Skill can change the result substantially. With home-assistant-best-practices installed, the model may tell you a helper beats a template sensor for a particular automation. Without it, it falls back on its own, possibly outdated, habits. The familiar comparison is HACS: the built-ins work, and the community sometimes offers something better suited to what you do.

Open Settings and select the Skills tab — third of the five along the top, between Models and Sub-agents.

Where Skills liveSettings, Skills tab, before anything is installed.

• No skills found fills the left column. That column is the installed list, so an empty one is the correct first state.
• + Add skill sits at the foot of that column — the only control on this screen, and where every install starts.
• Select a skill is the placeholder in the right-hand pane, which fills with a Skill's detail or with the Add skill form.

Four ways to name a package, and one that gets rejected

Search finds what somebody listed in the catalog. Everything else — an unlisted repository, an npm package, a folder already on your host — installs by package specification, the argument of the command the panel fronts: pi install <package-spec>. Pi Agent is built on @earendil-works/pi-coding-agent, whose command-line interface is pi. A specification has a defined syntax; a repository name you recognize is not one. Four source types are valid.

One more rule, easy to miss: references stay pinned. @v1 keeps meaning v1; an update refreshes that checkout rather than moving you to v2. Changing refs is a fresh install, covered below.

Nothing here assumes GitHub. Replace the host — git:gitlab.com/user/repo, git:codeberg.org/user/repo, or your own server at git:git.your-domain.tw/user/repo.

All four forms end at the same discovery step. Pi scans three directories for folders containing a SKILL.md: ~/.pi/agent/npm/, ~/.pi/agent/git/, and ~/.pi/agent/skills/. That last is a symlink to /data/pi-agent/skills/, where hand-written Skills go — do not look for an installed Git package there. Because $HOME is pinned into the add-on's data volume, panel and command line see the same Skills, and a Home Assistant snapshot brings the collection back with it: skills/, npm/, git/, and the enabled state in ~/.pi/agent/settings.json.

Whether a source works then depends mostly on authentication.

Install a real Skill, then prove the agent can see it

Press + Add skill and the right-hand pane fills in.

Add skillOne search field, one scope switch, one link to the catalog.

• The field wants a keyword, not an address. Its placeholder reads e.g. react, testing, deploy, and the blue Search button queries the skills.sh catalog.
• global / project decides which settings file records the install. Global writes to ~/.pi/agent/settings.json, project to .pi/settings.json beside your working directory. The arrow names the selected scope's path, ~/.pi/agent/skills/. Leave it on global unless you need a per-project Skill.
• skills.sh is the link on the last line — the community-curated directory, and the closest thing to an official Skill store.

1. Step 1

   Search for it, or install it by specification

   Select + Add skill, type mattpocock and select Search. This walkthrough uses mattpocock/skills: not useful at home, but it installs reliably. The panel calls /api/skills/search; matching cards come back with their own Install button. If the catalog does not list what you want, open a terminal attached to the add-on and run one of these:

   pi install git:github.com/mattpocock/skills

   pi install https://github.com/mattpocock/skills

   pi install git:github.com/mattpocock/skills@main

   The third form pins a tag or commit. Do not enter bare mattpocock/skills.

2. Step 2

   Select Install and leave it alone

   The button reads Installing… while it works. Behind it the panel posts to /api/skills/install with {cwd, package, scope} and the backend runs pi install. Usually 5-30 seconds, depending on repository size and your connection. Do not cancel or refresh the page. It ends with a Package installed. toast.

3. Step 3

   Check the entry that appears

   The new Skill appears in the left column. Select it: the pane carries an enable/disable switch, Check Updates, Remove, and Installed Path — under ~/.pi/agent/npm/ for an npm package, ~/.pi/agent/git/<host>/<path>/ for a Git one.

4. Step 4

   Reload the session, not the page

   Reload Session usually sits at the upper right; select it and you should see Session reloaded. A new session works too. F5 does not — the system prompt is assembled when a session starts and is not reread part-way through, the most common reason a new Skill seems to have vanished.

5. Step 5

   Find it in the system prompt, then use it once

   Open the read-only System Prompt panel and scroll to the <available_skills> block; your Skill's name should be inside it. That proves Pi found it — not that the agent will use it well. So name it in a test request too: “Please use Skill name to help me do XX.” If the reply engages and the right tools appear, it works.

6. Step 6

   Read its SKILL.md before you rely on it

   SKILL.md is the file Pi reads, not README.md: it holds the name, description and allowed-tools frontmatter fields, and should say what triggers it, which tools it needs and which environment variables it expects. Follow Installed Path to it — /data/pi-agent/home/.pi/agent/git/<host>/<user>/<repo>/SKILL.md for a Git package, the matching …/npm/… path for an npm one. Five minutes of reading beats half an hour of guessing.

Every installed Skill is stapled to the front of every conversation, relevant or not, so remove the ones you do not use. Two ways, for two situations.

From the panel, right in about 99% of cases: select the Skill, select Remove, confirm. The backend runs pi remove <spec>, drops the registration from settings.json, deletes the folder under ~/.pi/agent/git/… or ~/.pi/agent/npm/…, and shows a Package removed. toast. It cannot leave stale settings or delete the wrong path.

From a terminal attached to the add-on, when the panel is unavailable, the package is too damaged to list, or you are clearing several at once. Confirm the deployment-specific container name before using any host-level exec command, then:

One folder, one file, no programming

Published Skills address general needs — managing files, building websites. They know nothing about your household. Your own Skill is how you hand off the repetitive, specific work: photograph the refrigerator and get an inventory back, or answer a dishwasher error code from a manual you dropped in the folder.

The whole structure is one folder, one file:

Three elements go into it, and only two are required.

The filename is exact: SKILL uppercase, .md lowercase. Get the capitalization wrong and Pi will not find it. Markdown is the plain-text format you have seen on GitHub and in Obsidian — # makes a heading, - a list item — and if it is new to you, the agent still understands ordinary paragraphs.

Two notes on the frontmatter. name is the identifier: lowercase letters and hyphens, such as fridge-check, preferably matching the folder name. A non-ASCII name may work, but ASCII avoids path-encoding problems across operating systems. description matters most — the agent reads it to decide whether the Skill applies at all.

Here is the complete file. Copy it into SKILL.md:

Treat the Example output block as a template you refill for the next one: name, description, when to use, steps, safety, output shape.

Now get the folder onto the host. The fast route — about two minutes — is scp, or an SFTP client such as FileZilla or Cyberduck, into /data/pi-agent/skills/. Replace the host address with yours:

The slower route is GitHub, which buys version history and the ability to share it:

Then bring it back in: in the panel select Add from URL, paste the repository URL, select Install — or by specification, pi install https://github.com/your-account/fridge-check. Both routes end with the folder under /data/pi-agent/skills/. Iterate locally with scp while the Skill is rough, then push to GitHub once it has settled.

Finish by opening a new session, checking <available_skills> for fridge-check, then attaching a photo of your refrigerator — look it over for anything private first. The reply should describe what is visible, flag what to inspect, suggest dinner and list what to check next, in that order and without unsupported safety claims.

Three things that decide whether the agent uses it at all

Once a few are installed, writing quality decides almost everything. Three principles do most of that work.

Prohibitions are the part people leave out, and they matter because these systems are eager to help. Leave the boundary unstated and an inventory drifts into an invented nutrition report, or into claims about bacteria and illness. Blunt instructions — “do not diagnose,” “do not infer safety from an image” — keep the output useful and appropriately limited. Do not overcorrect either: a wall of “must” and “absolutely never” makes replies sound scripted, so use “prefer,” “usually” or “avoid” where judgment is genuinely appropriate, and keep the real prohibitions firm.

flowchart TD
  A["The agent ignored my Skill"] --> B{"Is it listed in the
available_skills block?"}
  B -->|"no"| C["Pi never loaded it.
Check the folder location
and the frontmatter"]
  B -->|"yes"| D{"Does the description name
the words you actually used?"}
  D -->|"no"| E["Rewrite the description
with concrete triggers"]
  D -->|"yes"| F["Try a model with stronger
instruction-following, and read
its tool calls, not just the reply"]

One more habit: keep each Skill to one job. A single-purpose description is easier to match, conflicts are easier to diagnose, and a change has a smaller blast radius — refrigerator inventory, dinner suggestions and grocery planning work better as three Skills than one, even when they refer to each other.

The same template, seven times over

Every entry below fills in the same blanks: repetitive work to delegate, rules the agent must follow, and approved reference material beside SKILL.md. Seven ideas, including the one you have built.

If one of yours is safe and useful outside your own house, publish it to a public GitHub repository so other people can read it before they install it. Four things to do first.

1. Step 1

   Confirm the repository really is public

   Open the repository on GitHub, go to Settings and scroll to the Danger Zone to check its visibility. A private repository cannot be fetched without authentication, so nobody else's install will work.

2. Step 2

   Strip anything private before the first push

   Credentials, personal information, internal hostnames, entity names, paths, household details. Once pushed to a public repository it is in the history, so do this before the push, not after.

3. Step 3

   Share a specification people can actually paste

   Do not tell anybody to enter your-account/fridge-check — Pi rejects bare shorthand. Give them the git: form or the complete https://github.com/… URL.

4. Step 4

   Add a README.md for the humans

   Explain what the Skill does, how to use it and what a sample conversation looks like, so somebody can decide whether it fits before installing. SKILL.md is written for the agent; README.md for people.

The failures you are most likely to hit

Start with the mechanical ones.

The rest of it

Where to go from here