---
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