Example Tool

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 version beyond 0.1.0 on initial creation.

4. Example session

User:  I want to add a skill that generates release notes from a git range.
Agent: I'll use example-tool as a template. Skill name: generate-release-notes?
User:  Yes.
Agent: Created /skills/generate-release-notes/SKILL.md from the template,
       updated frontmatter (name, triggers, inputs for git_range), rewrote
       the body, and added a row to SKILLS.md and skills/SKILL.md.
       Ready for review.

5. Testing this skill

Manual-test steps:

1. From a clean checkout, invoke the skill with target_name=test-skill.
2. Verify /skills/test-skill/SKILL.md exists and its frontmatter name is test-skill.
3. Verify new rows appear in both ../../SKILLS.md and ../SKILL.md.
4. Run scripts/validate-skills.sh (if present) and confirm exit 0.
5. git status should show only the new skill directory and the two catalog edits — nothing else.
6. Revert the test changes before committing.

6. Changelog

• 0.1.0 — Initial template skill.