> ## Documentation Index
> Fetch the complete documentation index at: https://docs.os.meetluno.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create skills

> Write a SKILL.md with clear task guidance.

A skill is a folder under `src/skills/` containing a `SKILL.md` and any supporting references. This page covers the format and the conventions that keep a skill useful.

## Create the folder

Make a folder named for the skill (the folder name is how you'll [attach it to an agent](https://docs.os.meetluno.ai/learn/skills/attach-skills-to-agents.md)) and add a `SKILL.md`:

```
src/skills/support/
  SKILL.md
  references/
    refund-policy.md
```

## Write SKILL.md

A `SKILL.md` follows the [Agent Skills specification](https://agentskills.io/specification): YAML frontmatter with a `name` and a `description`, then a focused body.

```md src/skills/support/SKILL.md theme={null}
---
name: support
description: Use when answering customer support questions about product policy, refunds, or tone.
---

# Support skill

Follow the refund policy in the product guide and keep replies concise.
Escalate billing disputes over $500 to a human.
```

| Frontmatter | What it does |
| - | - |
| `name` | The skill's name; match it to the folder name |
| `description` | Intent-based routing rule for when the agent should load this skill |

Write the `description` as a **Use when…** rule. Luno OS advertises attached skills to the agent as a compact catalog of names and descriptions, then the agent loads matching skills with `skill_view`. The description is the routing signal — describe the situation, not the file contents.

## Keep the body short, push detail to references

Skills work by **progressive disclosure**: the agent loads the short `SKILL.md` first via `skill_view`, then loads deeper material only when the task needs it. Keep `SKILL.md` to the essentials and put long policies, examples, and edge cases in a `references/` folder:

```
src/skills/support/
  SKILL.md                      # when to use it + the key rules
  references/
    refund-policy.md            # the full policy
    escalation-matrix.md        # detailed procedures
```

Reference files are a convention, not a fixed structure; name and organize them however reads best. Everything in the skill folder is materialized into the agent's workspace at `/workspace/agent/skills/{slug}/`. After loading `SKILL.md`, the agent can open a packed reference with `skill_view({ name, file_path })`.

References aren't the only kind of supporting material. The whole folder is copied verbatim, so a skill can also ship helper scripts the agent runs with its shell tools, or assets like templates and fixtures it reads:

```
src/skills/report/
  SKILL.md
  references/format.md
  scripts/build-report.ts
  assets/template.html
```

Point the agent at them by relative path from `SKILL.md`.

## Next steps

> **[Attach skills to agents](https://docs.os.meetluno.ai/learn/skills/attach-skills-to-agents.md)**
>
> Attach a skill to an agent by folder name.

> **[Skills overview](https://docs.os.meetluno.ai/learn/skills/overview.md)**
>
> What project skills are and when to use them.

> **[Import skills](https://docs.os.meetluno.ai/learn/skills/import-skills.md)**
>
> Reuse skills from external registries.

> **[Files](https://docs.os.meetluno.ai/learn/files/overview.md)**
>
> Add static reference documents to a workspace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.