Frank
02883d3ed2
Copy of the legacy ~/.pi/agent/docs tree rebuilt as the command-center knowledge base: concept files promoted to path identity, index listings stripped of frontmatter, all wikilinks/relative links resolved, every checkable claim verified against the live fleet (Dankserver = Ryzen 7 7700X + RTX 3090; Strix Halo is Dankclaw), unverifiable claims tagged. kb-lint exits 0.
49 lines
2.1 KiB
Markdown
49 lines
2.1 KiB
Markdown
---
|
|
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
|