Extending Paver with skills

Some tasks need deeper domain knowledge, whether it's the right commands for a specific service, the correct sequence for an incident response, the quirks of a particular platform, or expertise about your specific workflows. Skills are how IBM® Paver carries that knowledge.

A skill is a domain-specific capability module. Out of the box, IBM provides built-in system skills that cover the core capabilities of the environment Paver runs in. You can then extend Paver by adding your own user skills that are tailored to your specific workflows, proprietary tools, and custom runbooks.

When you ask Paver to do something, it automatically loads the skills relevant to your request and uses them to give more accurate guidance, actions, and recommendations. You don't need to choose or activate a skill yourself because Paver selects them for you.

What skills do#

Each skill adds focused expertise in a specific area. A skill gives Paver three kinds of knowledge:

• What to know: The terminology, resource types, and service quirks of a domain
• How to act: The right commands, flags, and workflows for a specific domain
• What to watch out for: The common mistakes, ordering dependencies, and safety considerations that apply

For example, when you ask Paver to manage IAM policies, it loads the iam-manager skill. That skill knows how service IDs, access groups, and trusted profiles work, and it guides Paver's actions accordingly.

How Paver selects skills#

Paver reads the description that is attached to every available skill and uses it to decide which skills apply to your request. Only relevant skills are loaded, which keeps Paver focused and avoids diluting its reasoning with unrelated context.

If your request spans multiple domains, for example deploying an app to Kubernetes with Terraform, Paver loads multiple skills at once. You never have to ask Paver to use a particular skill by name. Just describe what you want to do.

Skill tiers#

Skills come from two sources:

All skills are treated equally when Paver decides which ones to load for your request. Paver selects skills based on their descriptions, not on whether they are system or user skills. However, if a user skill has the same name as a system skill, your user skill replaces the system skill in your sessions only. To avoid replacing a system skill by accident, give your skill a unique name.

What's the difference between system and user skills?#

• System skills are provided and maintained by IBM for covering the core capabilities of the environment Paver operates in, such as interacting with platform services, managing infrastructure, and executing common operational tasks. They are available to all Paver users.
• User skills let you extend Paver beyond its baseline capabilities by adding expertise for your own proprietary tools, internal environments, and routine workflows. They apply only to your sessions.

Creating skills#

You can extend Paver's expertise by creating and uploading user skills that apply only to your sessions. Refer to the following requirements and recommendations for creating your user skills:

• Follow the open source Agent Skills Specification when you create your skill.
• Optionally include scripts, references, or assets subdirectories to enable the skill to execute code, load documentation as needed, or access-specific templates.
• Ensure the SKILL.md is ≤ 32 KB.                                                                    
• Files in your skill directory can't exceed a total of 50 MB. If your files exceed this limit, your skill won't be uploaded and you receive an error.
• Ensure that the SKILL.md file is in the root of your directory. This file is required.

Writing your own skill#

When you're writing your skill, you must include a SKILL.md file. You might also include other resources such as scripts, reference materials, templates, or other resources. A skill is a folder containing the following assets:

• SKILL.md (required): Instructions in Markdown with YAML front matter. Target fewer than 500 lines. 32 KB is the maximum file size limit.
• scripts/ (optional): Executable code. Scripts run in the Paver sandbox, where they have access to Python, Node.js, and Bash.
• references/ (optional): Documentation loaded as needed.
• assets/ (optional): Templates, fonts, icons used in output.

/skills/
|
|    skill_name/
|    |
|    |--- SKILL.md # Required - main skill file
|    |--- scripts/ # Optional - executable code
|         ├── process_data.py # Example
|         └── validate.sh # Example
|    |--- references/  # Optional - documentation
|         ├── api-guide.md # Example
|         └── examples/ # Example
|    |--- assets/  # Optional - templates, etc.
|         └── report-template.md # Example

The SKILL.md file contains the metadata and core instructions. The name and description of your skill are important because it is how Paver initially determines its relevancy for loading the skill based on the user request. The optional directories contain supporting resources that Paver can load as needed.

The YAML header in the SKILL.md file is what is loaded for Paver to evaluate and activate your skill based on the user request:

---
name: your-skill-name
description: Describe what it does. Define when to use it when a user asks to [specific phrases].
---

Make sure that the name defined in the metadata of the SKILL.md file matches the directory name. The description includes what the skill does and when it should be triggered. The description should be 1024 characters or less and not include XML tags. The primary purpose of the description is to help Paver decide whether to load the skill based on the user request. The description does not define how to complete a task based on the loaded skill.

Uploading skills#

You can upload skills from a GitHub directory or from your local system.

From inside a chat#

/skills upload ./skills/my-custom-skill

From the CLI#

paver skills upload ./skills/my-custom-skill

If you're not sure that the skill is uploaded or is available, you can list the skills in your session to verify:

paver skills list

Managing your skills#

You can list, upload, and remove user skills wherever you're working with Paver:

• In the web UI, you can manage user skills from the Skills page.
• In an interactive chat session in the web UI or paver chat, you can use the /skills slash command.
• In the CLI, you can use the skills command.

Refer to the IBM Paver CLI command reference and IBM Paver chat commands reference for full usage information about the commands.