Write and ship an Agent Skill

Package a workflow as a SKILL.md with scripts, validate it, test triggering, and install it via npx skills.

Run it as a prompt

Paste this into any AI agent, or fetch it: curl -s https://uplift.page/api/v1/prompts/agent-skill-authoring/raw

prompt.md

# Write and ship an Agent Skill

Ship one skill that agents load on at least 90% of 20 should-trigger prompts and at most 10% of 20 should-not prompts, with SKILL.md under 500 lines (about 5,000 tokens), passing skills-ref validate, and installable in 2 different agents with one command.

## Recommended stack

- **Agent Skills specification (agentskills.io)** - File format: SKILL.md frontmatter plus scripts/, references/, assets/. One open format read by many agents, with progressive disclosure so only name and description load until needed.
- **skills-ref 0.1 (installs the `agentskills` CLI)** - Validator. Checks frontmatter and naming rules (lowercase, hyphens, matches directory, max 64 chars).
- **skills CLI 1.7 (npx skills)** - Install from a git repo or local path. Installs into 75+ agents from GitHub, GitLab, any git URL, or a folder.
- **A small trigger/quality eval script** - Measures trigger rate and task quality with and without the skill. Description wording decides loading, and only a test shows if it works.

## Build steps

1. Pick one repeatable task agents get wrong without guidance; write down 3 examples of the task done well and 3 common failures.
2. Create `<name>/SKILL.md` where name is lowercase with single hyphens, at most 64 chars, and matches the folder.
3. Write the description (max 1024 chars) as a trigger: what it does plus "Use when ..." with the words users actually type.
4. Write the body: numbered steps, an input/output example, edge cases. Move long reference material to references/*.md (one level deep) and deterministic work to scripts/ with clear error messages.
5. Keep it agent-agnostic: no agent-specific tool names or paths; add the compatibility field only if it needs specific system packages or network access.
6. Validate with `agentskills validate ./<name>` (from `pip install skills-ref`; the spec page calls it skills-ref validate).
7. Install non-interactively with `npx skills add ./<name> -a <agent> -a <agent> -y` into 2 agents (set DISABLE_TELEMETRY=1 to opt out of the CLI's install telemetry), run 20 should-trigger and 20 should-not prompts in each, count a trigger when the agent's transcript or tool log shows it read <name>/SKILL.md, record trigger rates, and compare task quality with and without the skill on 5 tasks.
8. Push to a public repo and document the install line `npx skills add https://github.com/<owner>/<repo>/tree/main/skills/<name>`.

## Watch out for

- Vague descriptions ("Helps with PDFs") rarely trigger. Name the file types, verbs, and phrases users say.
- Putting everything in SKILL.md burns context on every load. Split into references and scripts.
- Uppercase letters, a double hyphen, or a folder-name mismatch fail validation and some installers.
- Scripts that assume a specific OS shell or a global tool without saying so fail silently in other agents.

## Definition of done

- `agentskills validate ./<name>` prints 'Valid skill' and exits 0.
- Trigger test shows at least 90% on positives and at most 10% on negatives in both agents.
- A fresh machine installs it with one npx skills command.
- With-skill output beats without-skill output on at least 4 of 5 tasks.

The full prompt

Recommended stack

Agent Skills specification (agentskills.io) - File format: SKILL.md frontmatter plus scripts/, references/, assets/. One open format read by many agents, with progressive disclosure so only name and description load until needed.
skills-ref 0.1 (installs the agentskills CLI) - Validator. Checks frontmatter and naming rules (lowercase, hyphens, matches directory, max 64 chars).
skills CLI 1.7 (npx skills) - Install from a git repo or local path. Installs into 75+ agents from GitHub, GitLab, any git URL, or a folder.
A small trigger/quality eval script - Measures trigger rate and task quality with and without the skill. Description wording decides loading, and only a test shows if it works.

Build steps

Pick one repeatable task agents get wrong without guidance; write down 3 examples of the task done well and 3 common failures.
Create <name>/SKILL.md where name is lowercase with single hyphens, at most 64 chars, and matches the folder.
Write the description (max 1024 chars) as a trigger: what it does plus "Use when ..." with the words users actually type.
Write the body: numbered steps, an input/output example, edge cases. Move long reference material to references/*.md (one level deep) and deterministic work to scripts/ with clear error messages.
Keep it agent-agnostic: no agent-specific tool names or paths; add the compatibility field only if it needs specific system packages or network access.
Validate with agentskills validate ./<name> (from pip install skills-ref; the spec page calls it skills-ref validate).
Install non-interactively with npx skills add ./<name> -a <agent> -a <agent> -y into 2 agents (set DISABLE_TELEMETRY=1 to opt out of the CLI's install telemetry), run 20 should-trigger and 20 should-not prompts in each, count a trigger when the agent's transcript or tool log shows it read /SKILL.md, record trigger rates, and compare task quality with and without the skill on 5 tasks.
Push to a public repo and document the install line npx skills add https://github.com/<owner>/<repo>/tree/main/skills/<name>.

Watch out for

Vague descriptions ("Helps with PDFs") rarely trigger. Name the file types, verbs, and phrases users say.
Putting everything in SKILL.md burns context on every load. Split into references and scripts.
Uppercase letters, a double hyphen, or a folder-name mismatch fail validation and some installers.
Scripts that assume a specific OS shell or a global tool without saying so fail silently in other agents.

Definition of done

agentskills validate ./<name> prints 'Valid skill' and exits 0.
Trigger test shows at least 90% on positives and at most 10% on negatives in both agents.
A fresh machine installs it with one npx skills command.
With-skill output beats without-skill output on at least 4 of 5 tasks.

Served from the uplift.page library and refreshed within 5 minutes of every update.