Date: 2026-09-11 Date: 2026-09-10

​
Skills

Use this lesson to build a practical, evidence-based Nova workflow for this topic.

​
What a skill is

A skill packages repeatable instructions, metadata, and optional supporting files into a workflow Nova can invoke. Skills are appropriate for tasks with a stable process, such as creating a particular report, applying a design standard, preparing a release, or managing a project-specific checklist. A skill is more than a saved prompt. Its frontmatter can control discoverability, arguments, allowed tools, model selection, and whether execution occurs in the current conversation or an isolated agent.

​
Skill locations and priority

Nova discovers skills from these locations, highest priority first:
  1. Project skills: .compass/skills/<name>/SKILL.md
  2. Project-scoped global skills: ~/.compass/projects/<project-slug>/skills/<name>/SKILL.md
  3. Personal skills: ~/.compass/skills/<name>/SKILL.md
  4. Built-in skills shipped with Nova
The project-scoped global location belongs to Compass-managed state. Use the exact project slug Nova resolves rather than inventing one. Project skills are suitable for workflows shared with a repository. Personal skills follow the user across projects. Built-in skills cover general capabilities delivered with Nova.

​
Directory structure

A minimal skill has one required file:
The directory can also contain templates, examples, scripts, or reference material used by the workflow. Keep each skill focused on one outcome.

​
SKILL.md format

Supported frontmatter includes:
  • name
  • description
  • argument-hint
  • disable-model-invocation
  • user-invocable
  • allowed-tools
  • model
  • context
  • agent
Nova also adds controlled metadata to skills created through its learning workflow.

​
Invocation

User-invocable skills are registered as slash commands under their skill name:
Skill content can use:
  • $ARGUMENTS for all supplied arguments.
  • $1, $2, and later positional placeholders.
  • @path file references, resolved relative to the project.
  • Supported command substitutions implemented by the skill processor.
A built-in slash command takes precedence if its name conflicts with a skill. Choose distinctive skill names. Nova can also invoke a skill automatically when its description clearly matches the request, unless disable-model-invocation: true is set. Set user-invocable: false for model-only internal workflows.

​
Inline versus forked execution

  • context: inline runs the skill in the current conversation and is the default.
  • context: fork runs the skill in an isolated child agent.
Use inline execution when the workflow needs the active conversation. Use forked execution for self-contained research, verification, or artifact generation that would otherwise add substantial intermediate context. Forked skills can choose an agent such as verification, explore, or supernova. Skills are not automatically inherited by spawned agents, so an agent definition must explicitly auto-load any skills it needs.

​
Tool restrictions

allowed-tools narrows what a skill may use. Prefer the minimum surface required by the workflow. A read-only review skill should not receive write tools. A release-check skill should be allowed to run verification commands but not publish artefacts. Shell patterns use forms such as Bash(npm:*). They are capability restrictions, not a guarantee that commands are safe. Runtime approval and organisation policy still apply.

​
Installing and discovering skills

Nova exposes tools for listing invocable skills, installing registry skills into project-scoped global storage, and invoking skills programmatically. In conversation, ask Nova what skills are available or use autocomplete to discover registered skill commands. Use the bundled find-skills workflow when the goal is to locate an installable skill rather than build one from scratch.

​
Designing a reliable skill

A good skill:
  1. Has one clear outcome and a precise description.
  2. States required inputs and uses an argument hint.
  3. Defines observable completion criteria.
  4. Restricts tools and side effects.
  5. Handles missing inputs and failure states.
  6. Distinguishes preview from destructive or external action.
  7. Avoids secrets and machine-specific assumptions.
  8. Includes only supporting material needed for execution.
Test the skill in a disposable project before sharing it broadly.

​
What you learned

You can now apply the core practices in this lesson during a Nova session.

​
Try it yourself

Use this lesson’s guidance in a small, non-destructive task in a local project, then review the result before continuing.

​
Continue the course