---
type: guide
title: Skill Author Best Practices
description: Tips for writing good skill descriptions, organizing files, and distributing pi packages on npm.
tags:
  - unverified
  - skills
  - best-practices
  - authoring
timestamp: 2026-07-18
verified: 2026-08-28
---

# Best Practices for Skill Authors

## Description Writing

1. **Be specific about capabilities** — "Extracts text and tables from PDF files, fills forms, merges documents" vs "Helps with documents"
2. **Include trigger phrases** — "Use when working with PDF files or when user mentions PDFs, forms, or document extraction"
3. **Keep under 1024 characters**
4. **Write in third person**
5. **First sentence = what it does, second sentence = when to use it**

## File Organization

1. **Use progressive disclosure** — Keep SKILL.md focused; reference detailed docs in `references/`
2. **Add scripts for deterministic operations** — When the same code would be generated repeatedly, scripts save tokens and improve reliability
3. **Split files when content exceeds ~500 lines** — Agents load the entire file on activation
4. **Include a config.json** for configurable paths or settings
5. **Add tests** — Include test scripts and mock data for validation

## Security

1. **Review skill content before use** — Skills can instruct the model to perform any action
2. **Scripts run with your full system permissions** — Only install from trusted sources
3. **Document dependencies clearly** — List all required tools, API keys, and setup steps

## Distribution

1. **Add `pi-package` keyword** to package.json for npm discoverability
2. **Include `video` or `image` fields** in the pi manifest for the gallery
3. **Use peerDependencies** for pi-provided packages: `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai`, `typebox`
4. **List runtime deps in `dependencies`** — They get installed automatically

## Related

* [Package Structure](/tools/npx-skills/package-structure.md) — How to structure your npm package
* [Installation](/tools/npx-skills/installation.md) — How users will install your skills