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.
66 lines
2.0 KiB
Markdown
66 lines
2.0 KiB
Markdown
---
|
|
type: reference
|
|
title: Skill File Structure
|
|
description: The directory structure of a skill — SKILL.md as the required entry point, with optional scripts, references, and assets directories.
|
|
tags:
|
|
- unverified
|
|
- skills
|
|
- structure
|
|
- SKILL.md
|
|
timestamp: 2026-07-18
|
|
verified: 2026-08-28
|
|
---
|
|
|
|
# Skill File Structure
|
|
|
|
A skill is a **directory** with a `SKILL.md` file. Everything else is freeform.
|
|
|
|
## Standard Structure
|
|
|
|
```
|
|
my-skill/
|
|
├── SKILL.md # Required: frontmatter + instructions
|
|
├── scripts/ # Helper scripts (bash, js, python, etc.)
|
|
│ ├── process.sh
|
|
│ └── analyze.js
|
|
├── references/ # Detailed docs loaded on-demand
|
|
│ ├── api-reference.md
|
|
│ └── FORMS.md
|
|
├── assets/ # Templates, configs, binary data
|
|
│ └── template.json
|
|
├── config.json # Skill-specific configuration
|
|
└── tests/ # Test scripts (optional)
|
|
└── test_runner.sh
|
|
```
|
|
|
|
## Real Example: zim-knowledge-base
|
|
|
|
```
|
|
zim-knowledge-base/
|
|
├── SKILL.md # Main skill instructions
|
|
├── config.json # ZIM file path configuration
|
|
├── scripts/
|
|
│ ├── search.sh # Search ZIM file index
|
|
│ ├── extract.sh # Extract article as HTML
|
|
│ ├── list.sh # List article titles
|
|
│ └── metadata.sh # Get article metadata
|
|
└── tests/
|
|
├── mock_zimdump.sh # Mock for testing
|
|
├── test_runner.sh # Test harness
|
|
└── test_zim_file.zim # Test fixture
|
|
```
|
|
|
|
## Real Example: brave-search (from badlogic/pi-skills)
|
|
|
|
```
|
|
brave-search/
|
|
├── SKILL.md # Setup + usage instructions
|
|
├── search.js # Brave Search API wrapper
|
|
└── content.js # Page content extraction
|
|
```
|
|
|
|
## Related
|
|
|
|
* [Skills Specification](/tools/npx-skills/skills-spec.md) — Frontmatter fields and requirements
|
|
* [Best Practices](/tools/npx-skills/best-practices.md) — File organization tips
|