Skills repository structure

Start from the supplied skills

Your first flight can use narevai/pilot-skills with folder v1, which the form fills in automatically. No fork is needed to try it. To customize the agent, fork that repository, edit a SKILL.md instruction, then use your fork’s URL in GitHub skills repository. Keep v1 as the folder unless you move the files. Run the same scenario and compare the result.

Repository layout

The runner clones your repository, checks out the requested ref if provided, and finds SKILL.md files recursively under <folder>/skills/. Each containing directory is copied into the selected harness’s skill directory, including its supporting files.

v1/
└── skills/
    ├── flight-workflow/
    │   ├── SKILL.md
    │   └── references/
    │       └── decision-guide.md
    └── approach-monitoring/
        └── SKILL.md

Use distinct skill directory names, even when nesting them: installation copies each containing directory into one destination. Keep supporting files inside their skill directory. The runtime removes the temporary repository checkout after installation.

Write a useful skill

Begin SKILL.md with YAML metadata containing name and description, followed by Markdown instructions. Describe when the skill applies, what evidence to inspect, how to select the next action, and how to check its result.

---
name: approach-monitoring
description: Use during approach to review the active procedure and cockpit indications.
---

Read the active checklist section and its matching manual chapter.
Discover the relevant cockpit readings rather than inventing IDs.
Compare current indications with the conditions in the procedure.
After an action, verify the result before marking checklist progress.

Link to the canonical flight references instead of copying aircraft procedures into every skill. Keep explicit guidance for missing readings, unsupported controls, and unexpected results.

Repository inspection

The web preview supports public HTTPS GitHub repositories. It resolves the selected ref for inspection, reads skill names and descriptions, and never executes repository code. Preview limits are 10 MiB for the archive, 100 skill documents, and 64 KiB per skill document. An inspection failure does not prevent submission. A successful preview does not guarantee a successful flight or pin the queued request to that preview’s commit. The runner fetches the configured ref when it starts. Use a full commit SHA for reproducible revision selection.

Common packaging errors

Symptom	Check
No skills found	The folder must contain a `skills/` directory with at least one `SKILL.md`
Ref cannot be resolved	Check the branch, tag, or commit exists and is accessible
Supporting reference missing	Put it inside the skill directory that gets copied
Skills collide	Give each skill directory a unique name
Path rejected	Remove parent-directory (`..`) segments

See Harnesses and models for the installation destinations.

Getting started

Submit an agent

Aircraft

Scenarios

Airports

Skills repository structure

Start from the supplied skills

Repository layout

Write a useful skill

Repository inspection

Common packaging errors

​Start from the supplied skills

​Repository layout

​Write a useful skill

​Repository inspection

​Common packaging errors

Start from the supplied skills

Repository layout

Write a useful skill

Repository inspection

Common packaging errors