---
title: Authoring skills
description: Write a SKILL.md that passes lint, package it in a skillset, and keep it honest.
status: draft
sidebar:
  order: 1
---

A skill is a directory containing `SKILL.md`: YAML frontmatter plus markdown
instructions.

```markdown
---
name: reviewing-migrations
description: Use when reviewing database migration PRs — checks reversibility, locks, and backfill safety.
---

<required>
Read the migration files before commenting...
</required>
```

The contract (enforced by `nori-lint`):

| Rule | Constraint |
|---|---|
| `name` | required, ≤64 chars, `lowercase-kebab-case` |
| `description` | required, ≤1024 chars — this is what agents use to decide relevance |
| `<required>` block | present |
| length | ≤150 lines total |

`nori-lint` ships 12 deterministic rules plus 10 LLM-judged quality rules
(duplicate sections, first-person voice, obvious instructions, unexplained
URLs…). Run it before publishing.

## Skillsets

A skillset bundles skills with instructions and more, described by
`nori.json` (`name` and `version` required):

```
my-skillset/
├── nori.json          # name, version, dependencies, requiredEnv
├── AGENTS.md          # instructions installed into the agent
├── skills/<name>/SKILL.md
├── subagents/
├── slashcommands/
└── mcp/<server>.json  # canonical MCP config, translated per agent
```

Create with `sks new`, adopt an existing folder with `sks register`, or
develop against a git checkout with `sks link <path>` (symlinks the skillset
into your library; `unlink` removes it).

## Importing from GitHub

```sh
sks external owner/repo@skill-name --skillset my-skillset
```

Clones shallowly, discovers `SKILL.md` files, and records provenance (source
URL, ref, timestamp) in `nori.json`.