Build Your First Skill

Builds one standalone skill from canonical source and verifies its repo-local provider-native output.

This path adds Skillset to an existing repository, authors one source unit, and verifies its generated output. It assumes the global skillset command is available; see Install Skillset if it is not.

Initialize the repository

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

skillset init --json

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

skillset init --yes

The confirmed command writes the reviewed scaffold and also seeds .skillset/changes/state.json, the workspace’s initial release state. 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. 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 owns the complete command and option inventory.

Create one skill

Print a non-interactive source-scaffold plan:

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:

skillset new skill "Review Notes" --yes

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

---
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 owns the complete field and support contract.

Preview the build

Preview the render plan:

skillset build

The plan names the repo-local destinations 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 is adopted. Codex can consume that same physical tree as a provider delta; the nearby lock records one owner and both logical consumers instead of treating agents as a provider.

Write and verify

Write the reviewed plan:

skillset build --yes

Then prove the checked-in output matches source:

skillset check --only outputs

The comprehensive check should now pass too:

skillset check

Open one generated SKILL.md and its nearby skillset.lock. A rendered file may be an Agent standard projection, a 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:

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

That is the core source-first loop: edit canonical source, inspect drift, write deliberately, and verify.

Next

• Walk through the checked-in first-author example.
• Learn how rendering works.
• Use the development loop for daily work.
• If a command fails, start with troubleshooting.

Skillset renders files. It does not install, trust, activate, symlink, or mutate user-level provider configuration. See Build Versus Activation.