example-tool

name	example-tool
description	A template skill demonstrating the PAI SKILL.md format.
version	0.1.0
triggers	["when the user asks how to author a new skill","when an agent needs a template to copy"]
inputs	[{"name":"target_name","type":"string","required":true,"description":"kebab-case name of the new skill"}]
outputs	["a new directory under /skills/ with a populated SKILL.md"]
constraints	["must not commit secrets","must pass scripts/validate-skills.sh"]
examples	[{"prompt":"Create a skill that flashes a USB with the latest ISO","expected":"/skills/flash-usb/ with SKILL.md filled in"}]

example-tool

A reference implementation of the PAI SKILL.md convention. Copy this directory as a starting point for any new skill.

Related docs: ../../SKILLS.md, ../SKILL.md, ../../AGENTS.md, ../../TOOLS.md.

1. Purpose

example-tool exists so that contributors and agents have a known-good template to copy when creating a new PAI skill. It is not intended to perform useful work on its own — its value is that every field is populated, every required section exists, and the structure is easy to adapt.

2. Instructions

When this skill is triggered, the agent should:

1. Ask the user for target_name if it was not provided. The name must be kebab-case, lowercase, and not already present under /skills/.
2. Create the directory /skills/<target_name>/.
3. Copy /skills/example-tool/SKILL.md to /skills/<target_name>/SKILL.md.
4. Update the YAML frontmatter in the new file:
   • Set name to <target_name>.
   • Rewrite description, triggers, inputs, outputs, constraints, and examples for the new skill.
   • Reset version to 0.1.0.
5. Rewrite the body sections (Purpose, Instructions, Guardrails, Example session, Testing, Changelog) to describe the new skill.
6. Add a row for the new skill to the catalog table in ../../SKILLS.md and ../SKILL.md.
7. Run scripts/validate-skills.sh if it exists; otherwise prompt the reviewer to validate by hand.
8. Open a pull request.

3. Guardrails

The agent MUST NOT:

• Overwrite an existing skill directory without explicit user approval.
• Commit credentials, API tokens, or any file listed in .gitignore.
• Declare triggers so broad that the skill would activate for unrelated requests (e.g., "any request").
• Skip the catalog update in ../../SKILLS.md — a skill that is not in the catalog is effectively invisible.
• Increase beyond on initial creation.