skill-authoring
Create SKILL.md files that teach the agent new domains. Use when authoring a new pi skill with frontmatter, body structure, and references.
How do I install this agent skill?
npx skills add https://github.com/knoopx/pi --skill skill-authoringIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a set of instructional guidelines for authoring other skills. It contains no executable code, network operations, or sensitive data access.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerpass
1 file scanned · No issues
What does this agent skill do?
Pi Skills
Skills are Markdown files (SKILL.md) that teach the agent how to do something it doesn't know by default. Each skill covers one or more use cases within a single domain — e.g., "NixOS configuration management" with sub-areas for system updates, home manager, and package search. The agent loads the full file when the user's request matches the trigger description.
File Layout
my-skill/
├── SKILL.md # Frontmatter + workflow instructions (keep under 120 lines)
├── references/ # Deep docs loaded on demand (API specs, advanced patterns)
└── scripts/ # Helper scripts the agent runs directly
Assets go in assets/ for templates and files the agent uses in outputs. Scripts in scripts/ are deterministic code — not rewritten each invocation.
Frontmatter
Every skill requires name, description, and keywords. Additional fields depend on the skill type.
Required Fields
---
name: my-skill-name # kebab-case, matches directory name (max 64 chars)
description: "Does X. Use when Y."
keywords: ["keyword1", "keyword2", "keyword3"]
---
name: lowercase letters, numbers, hyphens only. No leading/trailing hyphens.description: quoted string. First sentence starts with a verb. Second starts with "Use when".keywords: array of single lowercase words used for scoring. Each word match scores 1.0 — you need at least 2 matches (score >= 2.0) for injection. Pick words users actually type. Avoid sharing keywords with other skills.
Optional Fields by Type
Tool skills (in tools/ directory, name = tool name):
related: [other-skill] # co-inject related skills
Knowledge skills (domain knowledge):
topic: State-Space Search # required — display heading in injected block
token_cost: 120 # estimated token budget (default: 150)
requires_tools: [read, find] # tools needed before this skill fires
Protocol skills (behavioral rules):
topic: Conventional Commits # required — display heading in injected block
Body Structure (under 120 lines)
# Skill Name
One-line summary of the domain this skill covers.
## Workflow / Commands
Step-by-step examples or command reference with inline code snippets.
## Details
Common variations, edge cases, or tricky parts specific to this domain.
## Constraints / Best Practices
Rules, gotchas, and things the agent must do (or not do).
See [deep reference](references/DEEP.md) for API specs and advanced usage.
- Workflow/Commands: numbered steps with concrete inline examples — command, code snippet, or config.
- Details: short context for variations on the main use cases.
- Link to
references/for anything deep. One level of linking only.
Examples from Existing Skills
Good — focused domain, multiple use cases:
# nh: one domain (Nix operations), three sub-domains (system updates, home manager, package search)
description: "Switches NixOS/Home Manager configurations, cleans old generations, and performs system maintenance. Use when running os/home switch, pruning the Nix store, or managing system generations."
Good — single use case within a domain:
# transcribe-audio: one domain (audio transcription), one primary use case
description: "Transcribes audio files to text using whisper-cpp. Use when converting speech to text, transcribing podcasts, lectures, or meetings."
Validation Checklist
-
nameis kebab-case and matches the directory name exactly -
descriptionis a quoted string with verb-first sentence + "Use when..." clause -
keywordsare single lowercase words, at least 3 per skill -
topicpresent for knowledge and protocol skills -
relatedlists logically connected skills for co-injection - Body is under 120 lines (move excess to
references/) - At least one concrete inline example per key concept
- No duplicated content between SKILL.md and references
- All file links resolve to existing paths
- Keywords don't collide with other skills
Common Mistakes
- Description uses
>chevron instead of"quoted"— convert to quoted string - Missing "Use when..." clause — add trigger conditions
- Duplicate content between SKILL.md and references — keep detail only in references
- Long explanations of concepts the agent already knows — delete them
- Extra files the agent never reads (README, changelog) — remove them
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/knoopx/pi/skill-authoring">View skill-authoring on skillZs</a>