Write your first Skill

Why write your own Skill?

Installing someone else’s Skill is convenient: find it online, paste the URL, and install it to give the AI a new capability. Most published Skills, however, address general needs such as managing files or building websites. They do not reflect the routines and preferences of your household.

Writing your own Skill lets you delegate repetitive, household-specific work to the AI. For example:

• Instead of checking every refrigerator shelf each week, take one photo and ask for an inventory of the visible food.
• When you cannot decide what to cook, ask for ideas based on the available ingredients and your household’s preferences.
• Generate a grocery list from an agreed weekly meal plan so that fewer items are forgotten.
• Place the digital manuals for your air conditioner, dishwasher, and dryer in a Skill, then ask what a documented error code means.

More importantly, writing a Skill is not programming. In ordinary English, describe what the AI should do when a particular situation arises. By the end of this chapter, you will have a working refrigerator-inventory Skill that you can adapt to other tasks.

A Skill is a Markdown document

At its simplest, a Pi Agent Skill is a folder containing a file named SKILL.md. That is all it requires.

The folder structure looks like this:

fridge-check/
└── SKILL.md          <- only required file

You may also place sample images, sample output, or additional reference documents such as PDF manuals in the folder. These are optional; only SKILL.md is required.

SKILL.md uses Markdown, a plain-text format commonly used on GitHub, Notion, and Obsidian. A # marks a heading, and a - marks a list item. Do not worry if Markdown is new to you: the AI can still understand a document written as ordinary paragraphs.

When Pi Agent starts, it scans /data/pi-agent/skills/ and treats each subfolder as a Skill. Place the fridge-check/ folder there, and it will appear in the Skills panel.

The three elements of SKILL.md

A usable SKILL.md has two required elements and one optional element:

What YAML frontmatter looks like

YAML represents data as key-value pairs, just like the YAML used in Home Assistant automations. The frontmatter in SKILL.md must contain at least these two fields:

---
name: fridge-check
description: When the user sends a photo of the refrigerator, list visible ingredients, identify items to inspect or use soon, and suggest dinner ideas
---

• name: The Skill identifier. Use lowercase English letters and hyphens, as in fridge-check or dinner-suggest, and preferably match the folder name. Non-ASCII names may work, but an English ASCII name avoids path-encoding problems across operating systems.
• description: The most important field. The AI uses it to decide whether the Skill applies to the current conversation. State the user’s likely words or actions as specifically as possible. The more concrete the triggers are, the more reliably the AI can select the Skill. The writing principles section returns to this point.

What the main instructions look like

Below the frontmatter, write ordinary Markdown. A common structure uses several sections beginning with ##:

• When to use this—Describe the exact situations in which the Skill applies: what the user says, does, or attaches.
• Steps—Tell the AI what to do and in what order: first, second, and third.
• Safety—State prohibited actions, likely failure modes, and relevant household constraints.

These headings and their order are not mandatory. What matters is that the AI can identify the trigger, the procedure, the expected output, and the boundaries after reading the document. The complete example in the next section makes this clearer.

A minimal working example: a refrigerator-inventory Skill

Here is the complete file. Copy this block into a file named SKILL.md:

---
name: fridge-check
description: Use when the user shares a refrigerator photo or asks what to cook. Inventory visible food, identify items that may expire soon, and suggest dinner ideas.
---

# Fridge Check Skill

Help the user inventory a refrigerator, assess visible freshness cues, and plan meals without inventing details.

## When to use this

Use this Skill when the user:
- Shares a refrigerator or freezer photo
- Asks what is in the refrigerator or what to cook
- Mentions ingredients, pantry items, leftovers, or food nearing expiration

## Steps

1. **Describe visible items first** — Use location, item, and approximate quantity. Say when a label or package is unclear; do not guess.
2. **Identify items to check soon** — Note visible signs such as yellowing leaves, damaged packaging, leaks, or discoloration. Explain that a photo cannot establish food safety.
3. **Suggest one or two dinner ideas** — Prefer ingredients that appear usable and should be consumed soon. Avoid requiring many extra purchases.
4. **Create a short use-next list** — Summarize which items the user should inspect or use first.

## Safety

- **Do not invent items that are not visible.**
- **Do not diagnose poisoning risk or provide medical advice.** If an item appears spoiled, advise the user to inspect it and discard it when in doubt.
- **Ask about available appliances and dietary requirements** before assuming a cooking method.
- **Use approximate quantities** when objects are partly obscured.
- **Reply in English** unless the user explicitly requests another language.

## Example output

```
[Refrigerator inventory]
- Upper shelf: one carton of milk, about four eggs, one bowl of leftovers
- Middle shelf: half a cabbage, two carrots, one package of tofu
- Produce drawer: one bunch of spinach; some leaves appear yellow

[Dinner ideas]
1. Spinach and egg stir-fry — uses the spinach and two eggs
2. Tofu with cabbage — uses the tofu and part of the cabbage

[Check or use next]
- Check the date and storage instructions on the milk
- Inspect and use the leftovers promptly if they have been stored safely
```

That is all. Apart from the small frontmatter block, the entire file consists of plain English. It is a complete, working Skill.

Install the Skill in Pi Agent

After writing SKILL.md, place it where Pi Agent can discover it. There are two approaches: a direct file transfer for quick testing, or GitHub for version control and sharing.

1. Create a folder on your computer

   In a familiar location, such as your desktop, create an empty folder named fridge-check/. Match the folder name to the SKILL.md frontmatter’s name field to prevent confusion.

2. Put SKILL.md in the folder

   Paste the complete example from the previous section into a file named SKILL.md (SKILL in uppercase and the .md extension in lowercase). If the capitalization is wrong, pi-web may not find it. Place the file in fridge-check/. The folder should now look like this:

   Desktop/
   └── fridge-check/
       └── SKILL.md

3. Option A: Direct file transfer (fastest, 2 minutes)

   Use scp or an SFTP client such as FileZilla or Cyberduck to connect to your Home Assistant host. Transfer the entire fridge-check/ folder into /data/pi-agent/skills/. With scp, use the following command, replacing homeassistant.local with your Home Assistant host address:

   scp -r ~/Desktop/fridge-check [email protected]:/data/pi-agent/skills/

   After the transfer, return to pi-web and press F5 to reload the page. As Chapter 15 explains, the Skills panel may not detect a new folder immediately. You should then see fridge-check in the Skills list.

4. Option B: GitHub (versioned and shareable)

   Turn fridge-check/ into a Git repository and push it to GitHub:

   cd ~/Desktop/fridge-check
   git init
   git add SKILL.md
   git commit -m "Initial fridge check skill"
   # Create a public repo called fridge-check on GitHub
   git remote add origin https://github.com/your-account/fridge-check.git
   git branch -M main
   git push -u origin main

   After pushing, return to Pi Agent’s Skills panel and select “Add from URL,” the field introduced in Chapter 15. Paste https://github.com/your-account/fridge-check, then select Install. Pi Agent will clone the repository, find SKILL.md, and list the Skill.

5. Confirm that the Skill is loaded

   The Skills panel should contain a fridge-check entry with a control for disabling or enabling it; it is enabled by default. Open a new Session, open the System prompt panel, and find the <available_skills> block. It should contain fridge-check and the description you wrote. If both appear, pi-web has added the Skill information to the system prompt.

Verify that the Skill works

Installation is only the first step. You must confirm that the AI follows the procedure in SKILL.md. Test it as follows:

1. Open a new Session

   A Skill is loaded into the system prompt when a Session begins, so you must open a new one. An existing Session will not automatically receive the new Skill. Select “New session” in the upper-right corner or “+” in the sidebar.

2. Select a reasoning-capable model

   First verify that the Skill was discovered and that its trigger is specific. Then compare a current reasoning-capable model through your configured OpenRouter route. Do not infer instruction-following quality from a model-family label alone; test the exact model with the same prompt.

3. Attach a refrigerator photo and a short request

   Take a photo of your refrigerator, check that it contains no sensitive information, and attach it to the pi-web conversation. Add the English prompt “Help me check the refrigerator. Reply in English,” then send it.

4. Review the response

   The AI should follow the steps in SKILL.md: describe what is visible, flag items to inspect or use soon, suggest dinner, and list what to check next. If the response follows the structure of the example output without making unsupported safety claims, the Skill is working.

5. If it does not work, check three things

   If the response does not follow the Skill, check the following items in order:

   • System prompt panel: Open the <available_skills> block and look for fridge-check. If it is absent, pi-web did not load the Skill. Return to the troubleshooting section in Chapter 15 and check the folder location and frontmatter syntax.
   • Description specificity: The AI uses the description to decide whether a Skill applies. “Help the user with housework” is too broad to match a request about the refrigerator. Use concrete triggers such as refrigerator photos, ingredients, pantry items, a refrigerator, or leftovers.
   • Model capability: If the Skill is present but ignored, try a model with stronger instruction-following and reasoning performance. Regardless of the model, review its tool calls and final output.

Three principles for writing an effective Skill

After testing several Skills, you will find that clear authoring strongly affects whether the AI selects and follows them. Apply these three practical principles:

Why are explicit prohibitions important? AI systems can be overly eager to help. If a boundary is not stated, the response may drift beyond the requested task. A refrigerator inventory might become an unsupported nutrition report or include claims about bacteria and illness. Clear instructions such as “do not diagnose” and “do not infer safety from an image” keep the output useful and appropriately limited.

Ideas for household Skills

Once you have written the refrigerator-inventory Skill, you can use the same template to create a collection of household Skills. Here are seven practical ideas:

The shared pattern is clear: a Skill combines repetitive work you want to delegate, rules the AI must follow, and approved reference material. Put the procedure in SKILL.md and the reference material in supporting files, and you have a purpose-built assistant.

Share your Skill with others

If your Skill is safe and useful beyond your own environment, push it to a public GitHub repository so that other people can inspect and install it.

1. Confirm that the repository is public

   On GitHub, open your repository, go to Settings, scroll to the Danger Zone, and confirm its visibility. A private repository cannot be fetched without appropriate authentication. Publish only after removing credentials, personal information, internal hostnames, and private household data.

2. Share a valid package specification

   Do not tell someone to enter the bare shorthand your-account/fridge-check; Pi does not accept it. As Chapter 15 explains, share a git-prefixed package specification or the complete URL represented by https://github.com/....

3. Add a README.md

   Place a README.md in the repository root to explain what the Skill does, how to use it, and what a sample conversation looks like. This helps people decide whether it meets their needs. SKILL.md is for the AI; README.md is for people. The two files serve different purposes.

4. Add it to a public index (advanced and optional)

   The Pi Agent ecosystem currently has no official central Skill index. Individual communities maintain scattered awesome-list-style collections. For visibility, consider the Home Assistant community, Reddit’s r/homeassistant, or the #pi-agent and #homeassistant tags on social platforms. There is no designated central index to which you should submit a pull request. In particular, do not treat “submit it to skills.sh” as official Pi Agent guidance.

Troubleshooting

1. The AI ignores the Skill completely

   Check two things. (1) The description may be too abstract: replace “help the user with housework” with a specific trigger such as “use when the user uploads a refrigerator photo.” (2) The model may not be following the instructions reliably: a lighter model such as GLM-4-Flash may handle complex instructions differently. Verify the exact configured model with a consistent test prompt, and compare a current reasoning-capable model such as GLM-4.6, Claude Sonnet 4, or DeepSeek-R1 when available. Chapter 12 explains reasoning models.

2. The Skill does not appear in the System prompt panel

   This means pi-web did not load SKILL.md. Frontmatter is the most common cause. Check that (1) both --- delimiters contain exactly three hyphens on lines by themselves, with no blank line before the first delimiter; (2) name: and description: are spelled correctly, with a space after each colon; and (3) the filename is exactly SKILL.md, with uppercase SKILL and lowercase .md. Open SKILL.md in a text editor such as VS Code or Notepad++ and confirm that it is encoded as UTF-8 without a BOM.

3. The Skill makes the AI’s responses rigid or unnatural

   Too many inflexible commands such as “must” and “absolutely never” can make the response sound scripted. Use guidance such as “prefer,” “usually,” or “avoid” where judgment is appropriate. Keep essential prohibitions firm, however—especially instructions not to invent facts, expose private data, take destructive action without approval, or provide unsupported medical advice.

4. I cannot use git push; how can I transfer the Skill to the Home Assistant host?

   There are two alternatives. (1) Use direct file transfer: drag the folder into /data/pi-agent/skills/ with an SFTP client such as FileZilla. (2) Ask Pi Agent to prepare the Git commands: attach your SKILL.md and say, “In English, explain and prepare the commands to push this Skill to my GitHub fridge-check repository. Do not run them without my approval.” If the AI uses the bash tool, review every command and destination before approval. The tool cards introduced in Chapter 9 show what the AI is doing.

5. The Skill works sometimes but not always

   The description may not cover enough trigger conditions. If it says only “use when the user uploads a refrigerator photo,” it may not match a text-only request about dinner. Include the likely English requests and relevant terms: description: Triggered when a user sends a photo of the refrigerator, asks “What's cooking today?” “What else is in the refrigerator?” “Show me the refrigerator,” or mentions ingredients, fridge, pantry, leftovers. More complete, specific triggers generally improve selection.

6. The AI still follows the old version after I change SKILL.md

   Skills are loaded when a Session begins. Open a new Session to load the revised SKILL.md. The system prompt in an existing Session does not update automatically, so always test a change in a new Session.

Frequently asked questions