How Skills Work in Sapience

Last Updated: 2026.01.23

What Are Skills?

💡

Wish Sapience could do “thing X”? Well, write out detailed instructions for it once, and now all your Agents can do it. This is like teaching on employee how to be a master of a given task/process, and then having all your employees instantly be able to do the same.

*Sapience Skills is a flexible and powerful system letting you add behavior and instructions to any Agent. Skills make Agents better!*

Skills are reusable instruction sets that tell AI agents HOW to work, WHAT to do, and WHY its important. Then you also tell them how to format or structure their responses.

Think of them as "work templates" that you can invoke when you need a specific output format. Claude Code is setting the internet on Fire with its “skills.md”, but Sapience has had this since 2024! 🙂

The best skills are written the way you’d write a process doc for a human employee, covering the who, what, when, why where of the job in question.

Sapience has always used skills under the hood, and that is most visible in the user-seleectable OUTPUT MODE, which are really skills, whereby detailed and structured instructions are given to the AI Agent as a hidden user message (and sometimes appended to the system and developer instructions sent to Agents).

Now, you can define your own user-scoped or org-scoped Skills yourself. Think of this as letting you have the ability to infinitely customize Sapience’s output modes, or even how it runs.

The feature is similar to Claude Code’s “skills.md” which is getting a lot of attention in 2026, but is much easier to use - without sacrificing any of the power.

Our key innovation (which Anthropic claims is novel to them, but that’s bollox) is combining baked-in Agent instructions with dynamically loaded instructions at runtime in the right context.

But, Claude Code’s skills are weak compared to Sapience!

Our innovation is combining core agent information (it knows about all skills, from the user, the org and globally) but it doesn’t load the detailed information about a given skill until it needs it.

We also allow Agents to think about Skills themselves and auto-invoke, something that as of Jan 2026 Claude Skills still lacks.

Built-in Global Skills:

Think of this as saving 1 or 2 pages worth of prompt instructions to the system, so you can use it again and again (and therefore is thematically similar to the Templates system of Sapience which is pervasive).

Detailed mode: selectable in the Chat interface, this gives you a whitepaper of at least 2000 words with structured output, a summary and a table synthesizing it.

Suggested topics: after most chat messages, you get a list of suggestions that you can click on to keep the conversation going.

Visual mode: heavily prompts the system to invoke the Sapience Coding Agent (if available) to build visuals for you.

There are about 20 built-in skills inside Sapience, so you’re using these all the time. For example, a Project Agent has a series of skills that relate to a Project. Same with a File Agent.

Make it Your Own

So if skills are built-in, what’s this article about? The real secret is defining your own skills or doing it for your orgnanization (org-scoped skills).

Example: You want a 10-point action plan. Instead of typing detailed instructions every time, you invoke the 10-point-plan skill, and the agent knows exactly how to structure its response.

Example: you’ve wired up some automations in Zapier or Make.com or n8n. They’re complicated. Rather than prompt an Agent to use those webhooks each time, create a skill that lays out all the key information about the automation and webhook… the URL, authentication details, and if you’re using the http_post tool, the JSON body format and structure. You write out those details once, and save, it, say as “my-webhook-skill”. Now, you can use the /my-webhook-skill in Chat, or in Scheduled Agent Jobs, and Sapience will dynamically load your skill at runtime and follow your rules.

💡

Combining Skills with HTTP Tools, or Skills with Schedule Jobs will level up your game immensely. It’s how you can create a team of Agents, with verify specific expertise, and then schedule them to work for you. Doing this, Sapience works as your employee 168 hours week instead of a human 40. This is one of the coolest features of Sapience.

Let’s have a look at how to create a Skill.

First, go to Menu > Settings & Customization > Agents > Manage Skills

You will see all the Skills available to you, combining Global Skills, Org-scoped Skills (your Org Admin creates these) and your own User-scoped skills.

Click the Actions dropdown menu, and click Add Skill

*When creating a new skill, you can accept the defaults for pretty much everything. The* ***bits to focus on*** are 1) name - make it very clear; 2) the description, make it short but very descriptive… this is what the AI uses to “know” what this thing is; 3) the LLM instructions: this is where you can add a LOT of detail.

Go ahead and create a new skill. Once you’re done, flip it from Draft to Active, and you can use it over in Chat. Its that simple!

Back on the manage skills screen you will now see something like this:

*Manage Skills window after adding a User-scoped Agent Skill.*

💡

Note: the number one trick for skills is to get the Name and Description right. If you write those poorly, the Agent will not know when or how to use this tool. The LLM instructions field is more forgiving and you can write a LOT of information in that field if you want to.

Two big tips for writing good skills, organize it either with HEADINGS, or with XML tags.

Headings: use the headings formatting and put in level 1 and level 2 headings

XML: this works surprisingly well. You can do it like this:

<CRITICAL> Always do these steps: 1. blah 2. blah </CRITICAL> <WORKFLOW> First, analyze the user’s question deeply. If it isn’t clear or if its contradictory, STOP, and ask clarifying questions. If you have the information you need, then de-compose the task into discrete units of work. Create a task for each of these items, and mark it as “to do”. Then… … </WORKFLOW>

💡

For those of you that are used to building Agents, then all of the rules and good practices relating to Prompt Engineering apply here. Use your knowledge!

The Skill Object

Every skill has these fields:

Required Fields

Field	Type	Description
`name`	string	Short identifier (e.g., "10-point-plan") - this is how the agent references it
`description`	string	One-line summary shown in the skill catalog
`llm_instructions`	string	The actual instructions the agent follows

Optional Fields

Field	Type	Default	Description
`display_name`	string	-	Human-friendly name (e.g., "10-Point Plan")
`status`	enum	`active`	`draft`, `active`, or `disabled`
`scope`	enum	`user`	`user`, `org`, or `global`
`injection_point`	enum	`system_prompt`	Where to inject: `system_prompt` or `user_message`
`is_agent_invocable`	bool	`true`	Can agents auto-invoke this skill?
`category`	string	-	Grouping category (e.g., "formatting", "analysis")
`tags`	list	`[]`	Searchable tags
`other_user_notes`	string	-	Your private notes about this skill

Status Lifecycle

DRAFT  →  ACTIVE  →  DISABLED
  │         │           │
  │         │           └── Temporarily hidden from catalog
  │         └── Visible and invocable
  └── Work in progress, not injected into agents

Using Skills At Runtime

Let’s have a look at how you use and invoke your skills.

Earlier in this article, we saw the 10-Point-Plan skill. You can also see it in the Manage Skills screen, because its a global built-in skill. So how do we use it? Easy!

*Find the skills selector in between the output mode dropdown (which are actually skills!) and the language selector.*

In the screenshot above, you can see we have selected the 10-Point Plan skill.

So, now we can just use it in Chat:

*An Agent using a Skill at runtime. Notice that the first thing it did was issue a tool call (emoji + text) and retrieved the skill instructions!*

In the screenshot above, we see that the Agent detected the skill, loaded it at runtime, and then got to work. It then checked the memories we have saved, then searched my workspace and the web.

Result? Not only did it give me a 10-Point Plan like the Skill says it should, but it went out and researched best practices for personal productivity, and applied those to my own data in notes about what I need to do. Thanks Sapience!

Sapience Skills vs. Claude Code's Skill System

If you've used Anthropic's Claude Code CLI, you may be familiar with its skills system. Here's how Sapience skills compare:

Feature	Claude Code	Sapience
Storage	Markdown files in `.claude/skills/`	Database objects (SOSkill)
Format	YAML frontmatter + Markdown body	JSON with typed fields
Invocation	Type `/skill-name` in CLI	Agent auto-invokes OR frontend passes `skill_uid`
Scoping	Project-level or User-level	USER, ORG, or GLOBAL scope
Discovery	Manual (`/` to list)	Auto-injected into agent system prompt
Agent Autonomy	Must be explicitly invoked	Agent can proactively use via `retrieve_skill` tool
Arguments	`$ARGUMENTS` placeholder	Not currently supported
File Support	Can include supporting files	Not currently supported

Key Differences

Claude Code uses file-based skills with a SKILL.md format:

---
name: explain-code
description: Explain a piece of code
argument-hint: [filename]
---
Explain the following code in simple terms:
$ARGUMENTS

Provide examples and potential improvements.

Sapience uses database-stored skills with structured fields, but you don’t need to worry about this, you can just use the GUI to manage skills (go to Menu > Settings & Customization > Agents):

{
  "name": "explain-code",
  "description": "Explain a piece of code clearly",
  "llm_instructions": "Explain the following code in simple terms...",
  "injection_point": "system_prompt",
  "status": "active",
  "scope": "user"
}

Why the Difference?

Multi-user Platform: Sapience is a web platform with multiple users and organizations - file-based storage doesn't scale

Sharing: Database storage enables skill sharing across organizations

Agent Autonomy: Agents can discover and use skills proactively, not just when you type a command

Access Control: Fine-grained permissions based on scope

Skills In-Depth

Skill Scoping

Skills have three scope levels that control visibility:

Scope	Who Can See It	Use Case
USER	Only you	Personal productivity skills, experimental skills
ORG	Everyone in your organization	Team-specific formats, company templates
GLOBAL	All users in the system	Platform-wide standards, shared best practices

Scope Examples

USER: Your personal "weekly-standup" skill that formats your weekly updates

ORG: Company's "incident-report" skill that follows your org's incident format

GLOBAL: Platform-provided "10-point-plan" skill available to everyone

How Skills Get Invoked

There are three ways a skill can be used:

1. Autonomous Invocation (Agent Decides)

The agent sees all your available skills in its system prompt:

<skills>
## Available Skills

[SKILL] 10-point-plan: Forces the agent to structure its response as exactly 10 numbered points
[SKILL] commit: Generate conventional commit messages
</skills>

When your request matches a skill's purpose, the agent can proactively call retrieve_skill to get full instructions and apply them.

Example:

You ask: "Give me a plan for improving team productivity"

Agent sees [SKILL] 10-point-plan in its catalog

Agent calls retrieve_skill(skill_name="10-point-plan")

Agent formats response with exactly 10 numbered points

2. Mandatory Invocation (Frontend Enforces)

When you select a skill in the UI before sending your message, the system adds a mandatory instruction:

**MANDATORY:** You MUST use the following skill in your response: [SKILL] 10-point-plan

This guarantees the skill format is applied.

3. On-Demand Invocation (You Request It)

You can explicitly mention a skill in your message:

"Use the 10-point-plan skill to give me steps for launching a product"

The agent will recognize this and apply the skill.

Live Example: The 10-Point Plan Skill

Here's a real skill that exists in the Sapience platform:

Skill Definition

{
  "uid": "skill-10-point-plan-global",
  "name": "10-point-plan",
  "display_name": "10-Point Plan",
  "description": "Forces the agent to structure its response as exactly 10 numbered points with a markdown heading",
  "scope": "global",
  "status": "active",
  "category": "formatting",
  "tags": ["structured-output", "planning", "list"],
  "injection_point": "system_prompt",
  "is_agent_invocable": true,
  "llm_instructions": 
"When the user invokes the /10-point-plan skill, you MUST structure your response as follows:
 1. Start with a level-one markdown heading: # 10-Point Plan for [TOPIC]
   - Replace [TOPIC] with a concise description of what the plan addresses
 2. Provide EXACTLY 10 numbered points - not 9, not 11, exactly 10
 - Each point should be a complete, actionable item
 - Use markdown numbered list format (1. 2. 3. etc.)
 3. Each point should be:
 - Clear and specific
 - Actionable or informative
 - Appropriately scoped for the topic
 
 Example format
 n# 10-Point Plan for [Topic]
 1. First point with clear action or information
 2. Second point building on the topic
 3. Third point...
 ...
 10. Tenth and final point
 
 CRITICAL: You must always provide exactly 10 points. If you cannot think of 10 distinct points, combine related ideas or add supporting/implementation points to reach exactly 10. Never provide fewer or more than 10 points."
}

How It Appears to the Agent

In the agent's system prompt, this skill appears as:

[SKILL] 10-point-plan: Forces the agent to structure its response as exactly 10 numbered points with a markdown heading

Sample Output

When invoked, the agent produces:

# 10-Point Plan for Launching a New Product 1. Define your target audience - Research and document the specific customer segment you're targeting 2. Validate product-market fit - Conduct customer interviews and analyze competitor offerings 3. Develop your unique value proposition - Clearly articulate what makes your product different 4. Create a minimum viable product (MVP) - Build the core features needed to solve the primary problem 5. Establish pricing strategy - Research market rates and determine your pricing model 6. Build your go-to-market plan - Define channels, messaging, and launch timeline 7. Set up analytics and tracking - Implement tools to measure adoption and engagement 8. Prepare customer support infrastructure - Create documentation, FAQs, and support channels 9. Plan your launch campaign - Coordinate marketing, PR, and social media activities 10. Define success metrics - Establish KPIs and review cadence for post-launch evaluation

Writing Effective Skills

Best Practices

Be Specific: Vague instructions produce inconsistent results

Bad: "Make it good"

Good: "Use exactly 10 numbered points with markdown formatting"

Include Examples: Show the agent what you expect

Example format: # 10-Point Plan for [Topic] 1. First point...

Set Constraints: Tell the agent what NOT to do

CRITICAL: Never provide fewer or more than 10 points.

Use Clear Structure: Break instructions into numbered steps

Test Your Skill: Try it with various prompts before marking it active

Common Skill Patterns

Pattern	Use Case	Key Instructions
Structured Output	Lists, tables, JSON	"Format as exactly N items..."
Tone/Style	Professional, casual, technical	"Write in a [tone] voice..."
Analysis Framework	SWOT, pros/cons, comparison	"Analyze using [framework]..."
Template Following	Reports, emails, documents	"Follow this template exactly..."
Role Playing	Expert perspectives	"Respond as a [role] would..."

Comparing Skill File Formats

Claude Code SKILL.md

---
name: 10-point-plan
description: Create a structured 10-point plan
---

When asked for a plan, structure your response as:

# 10-Point Plan for [Topic]

1. First point
2. Second point
...
10. Tenth point

Always provide exactly 10 points.

Equivalent Sapience Skill (API Create Request)

{
  "user_id": 61,
  "org_id": 1,
  "display_name": "10-Point Plan",
  "scope": "user",
  "payload": {
    "metadata_type": "skill",
    "name": "10-point-plan",
    "description": "Create a structured 10-point plan",
    "llm_instructions": "When asked for a plan, structure your response as:\n\n# 10-Point Plan for [Topic]\n\n1. First point\n2. Second point\n...\n10. Tenth point\n\nAlways provide exactly 10 points.",
    "status": "active",
    "injection_point": "system_prompt",
    "is_agent_invocable": true,
    "category": "formatting",
    "tags": ["planning", "structured-output"]
  }
}

Migration from Claude Code

If you're migrating from Claude Code's SKILL.md format:

SKILL.md Field	Sapience Field
`name`	`name`
`description`	`description`
(body content)	`llm_instructions`
`disable-model-invocation: true`	`is_agent_invocable: false`
File in `~/.claude/skills/`	`scope: "user"`
File in `.claude/skills/`	`scope: "org"` or `scope: "user"`

Note: Sapience doesn't currently support $ARGUMENTS placeholders. Arguments are passed naturally in the user's message.

Creating Your First Skill

Via the API

curl -X POST https://your-sapience-instance/api/v2/sapience/create \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": YOUR_USER_ID,
    "org_id": YOUR_ORG_ID,
    "display_name": "Weekly Standup",
    "scope": "user",
    "payload": {
      "metadata_type": "skill",
      "name": "weekly-standup",
      "description": "Format a weekly standup update",
      "llm_instructions": "Format the response as a standup update with three sections:\n\n## What I accomplished this week\n- List items\n\n## What I plan to do next week\n- List items\n\n## Blockers or concerns\n- List items (or \"None\" if no blockers)",
      "status": "active",
      "injection_point": "system_prompt",
      "is_agent_invocable": true
    }
  }'

Testing Your Skill

After creating, send a message like:

"Give me a weekly standup update. This week I finished the user auth feature and started on the dashboard. Next week I'll complete dashboard charts. No blockers."

The agent should format it using your skill's structure.

Troubleshooting

Skill Not Appearing in Catalog

Check status is active (not draft or disabled)

Verify scope matches your context (USER skills only appear for you)

Ensure the skill was saved successfully (check API response)

Agent Not Using the Skill

Make sure is_agent_invocable is true

Try being more explicit: "Use the [skill-name] skill to..."

Check if the skill's description matches your request

Inconsistent Output

Add more specific constraints to llm_instructions

Include examples of expected output

Add "CRITICAL" or "MUST" for non-negotiable requirements

Summary

Skills in Sapience are powerful tools for getting consistent, structured responses from AI agents. Unlike Claude Code's file-based system, Sapience skills are:

Database-stored for multi-user platforms

Auto-discovered by agents through the skill catalog

Scope-controlled for personal, org, or global visibility

Proactively usable by agents without explicit invocation

Start by creating a simple USER-scoped skill for a format you use often, test it thoroughly, and then consider promoting it to ORG or GLOBAL scope if others would benefit.

Docs Agent

Sapience Skills - A Superpower