Product Guides

Skills

Teach Opulent reusable procedures by committing SKILL.md files to your repos

What are Skills?

Skills are SKILL.md files you commit to your repositories that teach Opulent reusable procedures — any repeatable workflow you want Opulent to follow consistently. Testing your app before opening a PR, deploying to an environment, investigating a codebase, scaffolding a new service — if you can write it as step-by-step instructions, you can turn it into a skill.

A skill describes how to carry out a procedure. That is what separates it from a runbook, which describes when and why to operate in a lane and may point to one or more skills. Reach for a skill when the steps are fixed; reach for a runbook when the guidance is about judgment and scope.

Skills follow the open Agent Skills standard, so the same files work across multiple AI tools. Place them at .agents/skills/<skill-name>/SKILL.md in your repository. Opulent discovers them across all your connected repos, and the runtime scans the sandbox workspace path /opulent/workspace/.agents/skills/.

Why Skills Matter

Without skills, Opulent has to figure out workflows from scratch every session. With skills, you define a procedure once and Opulent follows it reliably every time. Skills are useful whenever you have a workflow that:

  • Should be done the same way every time — testing checklists, deployment steps, review procedures
  • Requires repo-specific knowledge — which services to start, what ports to use, which commands to run
  • Benefits from dynamic context — pulling in git diffs, branch names, or environment info at invocation time

Opulent Suggests Skills Automatically

Opulent can suggest skills for you. After it tests your application or learns something new about your setup during a session, it will suggest creating or updating a skill to capture that knowledge. You'll see a suggestion in your session timeline with:

  • A summary of what was learned (e.g. "how to start the backend with Docker")
  • The proposed SKILL.md file contents
  • A "Create PR" button to commit the skill to your repo

Over time, Opulent builds up a library of skills in your repo about how to run, test, and deploy your application.

Examples

Testing before opening a PR

A skill that tells Opulent how to verify a Next.js app before creating a pull request:

---
name: test-before-pr
description: Run the local dev server and verify pages before opening any PR that touches frontend code.
---

## Setup

1. Install dependencies: `npm install`
2. Start the database: `docker-compose up -d postgres`
3. Run migrations: `npx prisma migrate dev`
4. Start the dev server: `npm run dev`
5. Wait for "Ready on http://localhost:3000"

## Verify

1. Read the git diff to identify which pages changed
2. Open each affected page in the browser
3. Check for: console errors, layout issues, broken links
4. Screenshot each page at desktop (1280px) and mobile (375px) widths

## Before Opening the PR

1. Run `npm run lint` and fix any issues
2. Run `npm test` and confirm all tests pass
3. Include screenshots in the PR description

Deploying to an environment

A skill that deploys the app using arguments for the target environment, with dynamic content injection:

---
name: deploy
description: Deploy the app to a target environment and run smoke tests.
argument-hint: <environment>
triggers: ["user"]
---

## Deploy

1. Make sure you are on the correct branch for this deploy
2. Run `./scripts/deploy.sh $0`
3. Wait for the deploy script to complete successfully

## Verify

1. Curl `https://$0.example.com/health` and confirm a 200 response
2. Run the smoke test suite: `npm run test:smoke -- --env=$0`
3. Report the deployment URL and test results

## Current context

- Branch: !`git branch --show-current`
- Last commit: !`git log --oneline -1`

Invoking with @skills:deploy staging substitutes staging for $ARGUMENTS and $0, and the !`command` blocks inject live git info. The triggers: ["user"] field ensures Opulent only runs this skill when you explicitly ask for it — it won't auto-activate.

Investigating a part of the codebase

A skill for guided code exploration that restricts Opulent to read-only tools:

---
name: investigate
description: Research a part of the codebase and produce a written summary with file references.
allowed-tools: Read, Grep, ListDir
argument-hint: <topic or area to investigate>
---

## Research

1. Search the codebase for files related to: $ARGUMENTS
2. Read the most relevant files thoroughly
3. Trace the call chain and data flow

## Summarize

1. Write a summary of how $ARGUMENTS works
2. Include specific file paths and line numbers for every claim
3. Note any concerns, edge cases, or areas that need attention

The allowed-tools field restricts Opulent to read-only operations — no editing, no shell commands. This is useful for exploration tasks where you want analysis without side effects.

Skill Discovery

Opulent discovers skills from two sources, merged together at the start of every session:

  1. Indexed repos — Opulent's backend indexes SKILL.md files across all repositories connected to your organization. These are available immediately when a session starts, before any repos are cloned.
  2. Cloned repos — As repositories are cloned onto the session's machine, Opulent scans them for SKILL.md files on disk. Disk-scanned skills update or override any matching indexed skill from the same repo, ensuring Opulent always uses the latest version on the branch being worked on.

When a repo clone completes mid-session, Opulent automatically re-scans that repo so newly added or modified skills are picked up without restarting.

Supported Skill File Locations

Opulent searches for SKILL.md files in all of the following directories:

  • .agents/skills/<skill-name>/SKILL.md (recommended)
  • .github/skills/<skill-name>/SKILL.md
  • .claude/skills/<skill-name>/SKILL.md
  • .cursor/skills/<skill-name>/SKILL.md
  • .codex/skills/<skill-name>/SKILL.md
  • .cognition/skills/<skill-name>/SKILL.md
  • .windsurf/skills/<skill-name>/SKILL.md

All seven paths are scanned in every repo.

What Opulent Loads from a Skill File

When a skill is discovered, Opulent parses the YAML frontmatter (the --- block at the top) and extracts:

Field Purpose
name Identifies the skill. Falls back to the parent directory name if omitted.
description Short summary shown in the skill list so Opulent (and you) know what the skill does.
allowed-tools Restricts which tools Opulent can use while the skill is active.

Opulent also supports these additional frontmatter fields beyond the standard spec:

Field Purpose
argument-hint Hint text shown alongside the skill name describing expected arguments.
triggers Controls who can invoke the skill — ["user", "model"] by default. Set to ["user"] to prevent Opulent from auto-activating it.

Everything after the frontmatter is the skill body — the step-by-step instructions Opulent is prompted to follow when the skill is invoked.

See the Agent Skills specification for the full file format reference.

Dynamic content

In addition to the standard spec, Opulent supports two kinds of dynamic content in the skill body that are processed at invocation time:

  • $ARGUMENTS — replaced with the full arguments string passed when the skill is invoked (e.g. via @skills:deploy staging prod). You can also access individual arguments by index: $ARGUMENTS[0] or $0 for the first, $ARGUMENTS[1] or $1 for the second, etc. Arguments are split by whitespace.
  • !`command` — the command is executed in the repo root and replaced with its stdout, letting skills include dynamic values like branch names or port numbers.

How Opulent Uses Skills

At the start of every session, Opulent sees a list of all available skills (name + description). When a skill is invoked, Opulent reads the full SKILL.md file and injects its body into its current context as a system-level instruction. This means Opulent actively follows the skill's steps for the remainder of the task — it's not just a reference, it directly guides Opulent's behavior.

Opulent can use skills in several ways:

Automatic invocation

When Opulent determines a skill is relevant to the current task, it invokes it automatically. For example, if you ask Opulent to fix a bug in frontend code and there's a test-before-pr skill, Opulent will activate it before opening the PR. Set triggers: ["user"] in the frontmatter to prevent auto-invocation for skills you only want triggered explicitly.

Mention a skill in your prompt

You can tell Opulent to use a specific skill by including @skills:skill-name in your message:

Fix the login bug on the /auth page @skills:test-before-pr

You can also pass arguments:

@skills:deploy staging

The arguments are substituted into the skill body wherever $ARGUMENTS, $ARGUMENTS[0], $1, etc. appear.

One active skill at a time

Opulent can only have one skill active at a time. Invoking a new skill replaces the previous one. When active, Opulent is prompted to follow the skill's steps in order and complete each one before moving on.

Searching and listing

Opulent can search for skills by keyword or directory if it needs to find the right one mid-session. You can also ask Opulent to list available skills or reload them after you've pushed changes to a skill file.

Limitations

  • Global / org-level skills — Today, skills live inside repositories. For org-wide skills, you can create a dedicated "skills" repo as a workaround. We're exploring first-class support for org-level skills that apply across all repos.
  • Composing multiple skills — Currently only one skill can be active at a time. We're working on support for chaining and composing workflows.

Skills vs. Playbooks

Both skills and playbooks give Opulent reusable instructions, but they work differently:

Skills Playbooks
Where they live In your repo as SKILL.md files — version-controlled alongside your code In the Opulent dashboard — managed through the UI
How they're triggered Opulent discovers and invokes them automatically, or you reference them with @skills:name in any prompt Manually attached to a session when you start it
Scope Scoped to a repo — Opulent picks up the right skills based on which repos are relevant to the task Org-wide — any team member can attach any playbook to any session
Auto-suggestion Opulent suggests new skills after testing your app or learning something new Created manually by team members
Best for Testing procedures, local dev setup, deployment checklists, repo-specific workflows Reusable prompt templates, cross-repo task patterns, onboarding guides

Which should I use? If your instructions are tied to a specific repo — how to run it, test it, or deploy it — use a skill. If your instructions are general-purpose prompts that apply across repos or teams, use a playbook. If the guidance is about when and why to operate in a domain lane rather than a fixed set of steps, capture it as a runbook instead.

Learn More

  • Agent Skills specification — the open standard for SKILL.md file format, frontmatter fields, and directory structure
  • Knowledge — for contextual facts and rules (not step-by-step procedures)
  • Playbooks — for reusable prompt templates attached to sessions