Skip to main content

Building a Skill

A Skill is a reusable, configured instruction for Revelry Ai. Where a prompt is a one-off message, a Skill packages three things so you get consistent results every time:

  1. Instructions: the base prompt text describing what to produce.
  2. Tool configuration: the model, built-in tools (Knowledge, Artifacts, Web Search, Workspace Agents), and integrations the Skill should use, plus how it runs in chat.
  3. Inputs: user inputs the person running the Skill fills in each time, and document attachments saved with the Skill.

Project context (your Project's name, overview, and details) is injected automatically, so you don't need to wire it in. Focus your effort on clear instructions and the right tool configuration.

A Skill is defined by its outcome​

What makes a Skill a Skill, and not just saved prompt text, is that it produces a specific result: either an output or a side effect, using tools you've pre-packaged so the result is the same every time it runs.

  • Output: a concrete deliverable. Most often an Artifact of a defined type: a user story, a design doc, a report, a summary. The Skill knows what it's meant to generate, so you're not re-describing the target each time.
  • Side effect: an action in a connected system. With an integration enabled, a Skill can create a Pipedrive deal, open a GitHub issue, or post a message. A repeatable operation, not just text.

The key idea is pre-packaging the tools with the instruction. A Skill carries its own model, Knowledge scope, artifact setting, and integrations, so whoever runs it (in chat, in a Workflow, via the API, or as a Skill invoked by an Agent) gets a dependable, self-contained capability instead of a prompt they have to set up correctly first. Design a Skill by starting from the outcome you want, then wiring in exactly the tools that outcome needs.

This is a big part of what makes Skills worth building: users don't have to remember which tools to turn on. The right capabilities are already enabled and scoped, so someone can just ask for the outcome.

  • A marketing SEO Skill can ship with web search on and a few specific reference pages attached (say, from a website-crawl data source of your docs site), so a user just says "audit this page for SEO" and the Skill already knows where to look. No toggling tools, no pasting links.
  • A file-a-bug Skill can ship with the GitHub integration enabled, so it creates the issue directly. (See the connection note under Integrations; a Skill that depends on an integration should say so in its instructions.)

Creating a Custom Skill​

  1. Click Tools in the left navigation, then the Skills tab. The first card, Build Your Own, has a Build a Skill button. Click it.
  2. Give the Skill a Name and an optional Description. The name also sets the Skill's slash command: a Skill named "Meeting Notes Summary" runs from chat as /meeting-notes-summary. Renaming the Skill updates the command.
  3. Choose an Operating Mode: Inline, Subagent, or Auto (see Operating Mode below).
  4. Write your instructions, the base prompt text the AI will follow. For techniques that make this text effective, see Prompt Engineering.
  5. Configure the tools the Skill should use from the Chat Tools menu (the + button under the instructions) and the Model selector next to it (see below).
  6. Add any user inputs the Skill needs to collect at runtime, and attach any documents it should always have on hand.
  7. Choose how to finish:
    • Save: store the Skill in your library for later use.
    • Try It Out: save the Skill and immediately open a chat with it.

Save is disabled until the instructions have content and any input placeholder errors are resolved.

Artifact Type and Category are optional. Artifact Type is deprecated and only needed if an external v1 artifact integration still relies on the Skill's artifact type slug. Category groups related Skills and artifacts within your Projects.

Operating Mode​

The Operating Mode setting decides how the Skill runs when someone invokes it from chat:

  • Inline: always run in the current chat. The Skill sees the conversation so far, runs on the conversation's current model, and you can steer it as it goes. Best for quick edits and conversation-driven work.
  • Subagent: always run in a separate, isolated chat session with the Skill's own model and tools, returning only the final result. Best for long research tasks, large outputs, and Skills that need a specific model.
  • Auto: let the assistant choose between the two based on the task.

See Executing Skills for how each mode behaves.

Configuring Tools​

Tool configuration is what turns a good prompt into a dependable Skill. Each setting below is saved with the Skill and applied automatically whenever it runs: in chat, in a Workflow step, or via the API.

Tools are configured from the Chat Tools menu under the instructions, the same + menu you use in chat. A badge on the button shows how many tools are enabled. The menu has three parts: Context (attach documents), Built-in Tools (toggles), and Integrations.

Model​

A Skill can pin which AI model to use for generation, overriding your organization's default. Match the model to the task: a model with stronger reasoning for complex analysis, or a faster model for routine drafting.

  1. Open the Skill in the Skill builder.
  2. Use the Model selector next to the Chat Tools button.
  3. Search for and select the desired model, or leave it on the organization's default.

Note: A pinned model applies when the Skill runs in its own session (in a Workflow, via the API, or as a Subagent in chat). When a Skill runs Inline, it uses the conversation's current model. See How Skills run in chat.

Built-in Tools​

Toggle each built-in tool on or off under Built-in Tools in the Chat Tools menu. Only tools your organization has enabled appear.

  • Knowledge: search your organization's Knowledge Base while the Skill runs. Use Advanced at the bottom of the menu to narrow the search to specific Collections, Data Sources, or document Types. Scoping keeps results focused; point a Skill at exactly the sources relevant to its task instead of the entire Knowledge Base.
  • Artifacts: search and create Artifacts within the project. Enabled by default. Leave it on for Skills meant to produce an Artifact; turn it off for Skills that only research, analyze, or answer. With it off the AI cannot create, update, or find artifacts.
  • Web Search: search the web in real time for up-to-date information.
  • Workspace Agents: run automated agents in an isolated workspace to process files, execute code, and complete multi-step tasks.

Integrations​

Pre-configure which external integrations are active when the Skill runs, using the Integrations entry in the Chat Tools menu, the same controls found in the chat's Tools menu. For example, a Skill can automatically enable Pipedrive tools for CRM work or GitHub tools for engineering tasks, so users don't have to turn them on manually.

Integrations act as the person running the Skill, using their own connection. A "File a GitHub Issue" Skill, for instance, creates the issue under the current user's GitHub connection, so the issue is attributed to them, and it only works if they've connected GitHub.

Write for the missing-connection case. Because an integration relies on the user's own connection, always state the dependency in the Skill's instructions and tell the AI how to respond when it's absent. For example:

"This Skill creates a GitHub issue using the user's GitHub connection. If the GitHub tools are not available, do not attempt to proceed. Tell the user they need to connect GitHub first and explain how, then stop."

This turns a silent failure into a clear, helpful message. See Treat errors as an output.

Collecting Inputs​

Beyond the automatic Project context, a Skill can gather information from the person running it, and carry reference documents of its own.

User Inputs​

User Inputs are fields filled in each time the Skill runs, letting one Skill adapt to many situations. Inputs can be text or a document attachment.

User Inputs live in the panel to the right of the instructions. Click New User Input to add one:

  • Input Name: a clear, descriptive label. This is the field label the user sees when the Skill runs.
  • Input Type: Text or Document Attachment.
  • Input Description: requirements and guidance so users know what to provide.

Examples:

  • Text: Name: "Feature Description", Type: Text, Description: "Briefly describe the feature."
  • Document: Name: "Design Specifications", Type: Document Attachment, Description: "Upload the design specs."

Each input appears as a card in the right panel showing its type and description, with a count of how many times the instructions reference it. Click the + on a card to insert its placeholder, such as {custom.Feature Description}, at your cursor in the instructions. Edit an input in place from the card's menu. The same panel lists your Organization Details, which you can insert the same way.

When a Skill runs from a slash command with a single text input, the text after the command fills that input. With several inputs, the assistant infers what it can from the message and asks for the rest. See Executing Skills.

Document Attachments​

Attach Documents directly to the Skill as fixed reference material. Useful when every run should reference the same source (a style guide, a template, a spec).

Attaching works the same way it does in chat. Open the Chat Tools menu and, under Context, choose Upload New File or Select From Knowledge. You can also drag a file onto the Skill builder. Each attached document appears as a pill above the toolbar; remove it from the pill.

Design around inputs and outputs​

The most reliable Skills are the ones with the clearest contract. When building one, spend your effort at the two edges:

  • Inputs: what does the Skill need to do its job? Capture it explicitly as user inputs or document attachments rather than hoping the user includes it in their message. A single, well-described input ("Paste the page or URL you want audited") beats a vague prompt.
  • Outputs: what exactly should come back? Define the shape in the instructions: the artifact type, the sections or fields, the tone, the length. A Skill with a defined output is easy to trust and easy to reuse.

Nail those two and the middle mostly takes care of itself.

Treat errors as an output​

An error isn't a dead end. It's another thing the Skill can produce, and you should design for it. Anywhere the Skill depends on something that might not be there (a missing integration connection, an empty required input, no matching Knowledge, a tool that returns nothing), decide what the Skill should say and do, and put that in the instructions.

"If the input page can't be fetched, don't guess. Report which URL failed and ask the user to check it. If no relevant documents are found in Knowledge, say so plainly instead of inventing an answer."

Handling these cases explicitly is what separates a Skill that fails silently or hallucinates from one that gives a clear, actionable message. Treat every failure mode as an output you're choosing to design well.

Drafting a Skill with AI's Help​

You don't have to start from a blank page. Open a Chat and describe what you want the Skill to do: its role, the task, the audience, the output format, and a couple of example outputs. Ask Revelry Ai to draft the instructions, review the result, and refine until it's right. Then paste the text into the Skill builder, configure its tools and inputs, and save.

Next Steps​