nirholas/PAI / skills/example-tool
example-tool
VerifiedA template skill demonstrating the PAI SKILL.md format.
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:
- Ask the user for
target_nameif it was not provided. The name must be kebab-case, lowercase, and not already present under/skills/. - Create the directory
/skills/<target_name>/. - Copy
/skills/example-tool/SKILL.mdto/skills/<target_name>/SKILL.md. - Update the YAML frontmatter in the new file:
- Set
nameto<target_name>. - Rewrite
description,triggers,inputs,outputs,constraints, andexamplesfor the new skill. - Reset
versionto0.1.0.
- Set
- Rewrite the body sections (Purpose, Instructions, Guardrails, Example session, Testing, Changelog) to describe the new skill.
- Add a row for the new skill to the catalog table in ../../SKILLS.md and ../SKILL.md.
- Run
scripts/validate-skills.shif it exists; otherwise prompt the reviewer to validate by hand. - 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
versionbeyond0.1.0on 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:
- From a clean checkout, invoke the skill with
target_name=test-skill. - Verify
/skills/test-skill/SKILL.mdexists and its frontmatternameistest-skill. - Verify new rows appear in both ../../SKILLS.md and ../SKILL.md.
- Run
scripts/validate-skills.sh(if present) and confirm exit 0. git statusshould show only the new skill directory and the two catalog edits — nothing else.- Revert the test changes before committing.
6. Changelog
0.1.0— Initial template skill.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 465k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |