---
title: "Build Your First Skill"
slug: "skillset/start/quickstart"
description: Builds one standalone skill from canonical source and verifies its repo-local provider-native output.
---

<a id="build-your-first-skill"></a>

This path adds Skillset to an existing repository, authors one [source unit](/skillset/glossary/#source-unit), and verifies its [generated output](/skillset/glossary/#generated-output). It assumes the global `skillset` command is available; see [Install Skillset](/skillset/start/installation/) if it is not.

## Initialize the repository

From the repository root, print a non-interactive setup plan:

```bash
skillset init --json
```

The JSON result records an empty write set. Review it, then authorize initialization:

```bash
skillset init --yes
```

The confirmed command writes the reviewed scaffold and also seeds `.skillset/changes/state.json`, the [workspace's](/skillset/glossary/#workspace) initial [release state](/skillset/reference/features/releases/). That release-state seed exists only after confirmation and is not listed as a previewed scaffold write.

Initialization creates the root `skillset.yaml` workspace manifest and the `.skillset/` [source root](/skillset/glossary/#source-root). It does not change user-level provider configuration.

If you want a new repository dedicated to agent material, use `skillset create my-skillset --yes` instead. The generated [CLI reference](/skillset/reference/cli/) owns the complete command and option inventory.

## Create one skill

Print a non-interactive source-scaffold plan:

```bash
skillset new skill "Review Notes" --json
```

The JSON result records an empty write set. Review it, then rerun the same scaffold with explicit write authority:

```bash
skillset new skill "Review Notes" --yes
```

Edit `.skillset/skills/review-notes/SKILL.md` so it contains useful triggering guidance:

```markdown
---
name: review-notes
title: Review Notes
description: Use when turning meeting notes into decisions, follow-ups, and risks.
---

# Review Notes

- Identify concrete decisions.
- Pull out follow-ups and named owners.
- Keep unresolved risks separate from agreed next steps.
```

The directory name is the stable identity. `title` is display text, and `description` tells an agent when the skill is relevant. The [skill reference](/skillset/reference/features/skills/) owns the complete field and support contract.

## Preview the build

Preview the [render](/skillset/glossary/#render) plan:

```bash
skillset build
```

The plan names the repo-local [destinations](/skillset/glossary/#destination) that would change. `compile.targets` selects provider output such as `.claude/skills/` and `.cursor/skills/`. Separately, applicable skill source produces `.agents/skills/` whenever the Agent Skills [standard profile](/skillset/glossary/#standard-profile) is adopted. Codex can consume that same physical tree as a provider [delta](/skillset/glossary/#delta); the nearby [lock](/skillset/glossary/#lock) records one [owner](/skillset/glossary/#owner) and both logical [consumers](/skillset/glossary/#consumer) instead of treating `agents` as a provider.

## Write and verify

Write the reviewed plan:

```bash
skillset build --yes
```

Then prove the checked-in output matches source:

```bash
skillset check --only outputs
```

The comprehensive check should now pass too:

```bash
skillset check
```

Open one generated `SKILL.md` and its nearby `skillset.lock`. A rendered file may be an [Agent standard](/skillset/glossary/#agent-standard) projection, a [provider-native](/skillset/glossary/#provider-native) projection, or a shared physical file with both consumers; the lock records ownership, consumers, and hashes. Keep editing `.skillset/skills/review-notes/SKILL.md`, not the generated copy.

## Make one change

Change the authored skill body, then run:

```bash
skillset diff
skillset build
skillset build --yes
skillset check --only outputs
```

That is the core source-first loop: edit [canonical source](/skillset/glossary/#canonical-source), inspect [drift](/skillset/glossary/#drift), write deliberately, and verify.

## Next

- Walk through the checked-in [first-author example](/skillset/start/first-author/).
- Learn [how rendering works](/skillset/start/how-rendering-works/).
- Use the [development loop](/skillset/guides/development-loop/) for daily work.
- If a command fails, start with [troubleshooting](/skillset/troubleshooting/).

Skillset renders files. It does not install, trust, activate, symlink, or mutate user-level provider configuration. See [Build Versus Activation](/skillset/start/build-versus-activation/).