Skip to content

Commit 45d5717

Browse files
are-cesclaude
are-ces
and
claude
committed
LCORE-2077: Document Agent Skills feature
Add user-facing documentation for the Agent Skills feature: - Skills guide with configuration, SKILL.md authoring, and runtime behavior - Example skills (openshift-troubleshooting with references, code-review minimal) - Example lightspeed-stack-skills.yaml config file - README updates: Agentic Capabilities table and Agent Skills config section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 559753d commit 45d5717

6 files changed

Lines changed: 498 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ The service includes comprehensive user data collection capabilities for various
2020
* [Installation](#installation)
2121
* [Run LCS locally](#run-lcs-locally)
2222
* [Configuration](#configuration)
23+
* [Agentic Capabilities](#agentic-capabilities)
2324
* [LLM Compatibility](#llm-compatibility)
2425
* [Set LLM provider and model](#set-llm-provider-and-model)
2526
* [Selecting provider and model](#selecting-provider-and-model)
@@ -50,6 +51,7 @@ The service includes comprehensive user data collection capabilities for various
5051
* [System Prompt Literal](#system-prompt-literal)
5152
* [Custom Profile](#custom-profile)
5253
* [Control model/provider overrides via authorization](#control-modelprovider-overrides-via-authorization)
54+
* [Agent Skills](#agent-skills)
5355
* [Safety Shields](#safety-shields)
5456
* [Authentication](#authentication)
5557
* [CORS](#cors)
@@ -196,6 +198,19 @@ To quickly get hands on LCS, we can run it using the default configurations prov
196198
197199
# Configuration
198200
201+
## Agentic Capabilities
202+
203+
Lightspeed Core Stack supports the following agentic features:
204+
205+
| Capability | Status | Description |
206+
|------------|--------|-------------|
207+
| MCP Tools | Supported | External tool integration via [Model Context Protocol](https://modelcontextprotocol.io) servers |
208+
| RAG | Supported | Retrieval-Augmented Generation with vector stores ([RAG Guide](docs/rag_guide.md)) |
209+
| A2A Protocol (Client) | Supported | Agent-to-Agent communication as client ([A2A Protocol](docs/a2a_protocol.md)) |
210+
| Conversation History | Supported | Persistent conversation context across requests |
211+
| Human-in-the-Loop | Upcoming (Q2) | Interactive approval or confirmation steps |
212+
| Agent Skills | Upcoming (Q2) | Domain-specific instructions loaded on demand ([Agent Skills Guide](docs/skills_guide.md)) |
213+
199214
## LLM Compatibility
200215
201216
Lightspeed Core Stack (LCS) provides support for Large Language Model providers. The models listed in the table below represent specific examples that have been tested within LCS.
@@ -712,6 +727,25 @@ customization:
712727
713728
By default, clients may specify `model` and `provider` in `/v1/query` and `/v1/streaming_query`. Override is permitted only to callers granted the `MODEL_OVERRIDE` action via the authorization rules. Requests that include `model` or `provider` without this permission are rejected with HTTP 403.
714729
730+
## Agent Skills
731+
732+
Agent Skills allow product teams to extend Lightspeed Core with specialized instructions and domain knowledge that the LLM can load on demand. Skills follow the [Agent Skills open standard](https://agentskills.io) and are packaged as portable directories containing a `SKILL.md` file.
733+
734+
Skills are configured by specifying paths to skill directories in `lightspeed-stack.yaml`:
735+
736+
```yaml
737+
skills:
738+
paths:
739+
- "/var/skills/" # Directory containing skill subdirectories
740+
```
741+
742+
Each skill directory must contain a `SKILL.md` file with YAML frontmatter (`name` and `description`) followed by Markdown instructions. The LLM discovers available skills via tool calls and loads instructions on demand.
743+
744+
> [!NOTE]
745+
> Skills are configured by product teams at deployment time. End users do not have the ability to add skills.
746+
747+
For the full configuration guide, skill authoring instructions, and examples, see the [Agent Skills Guide](docs/skills_guide.md).
748+
715749
## Safety Shields
716750
717751
A single Llama Stack configuration file can include multiple safety shields, which are utilized in agent

‎docs/skills_guide.md‎

Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
# Agent Skills Guide
2+
3+
This guide covers how to configure Agent Skills in Lightspeed Core Stack and how to author your own skills.
4+
5+
---
6+
7+
- [Introduction](#introduction)
8+
- [Configuration](#configuration)
9+
- [Option A: Directory of Skills](#option-a-directory-of-skills)
10+
- [Option B: Individual Skill Paths](#option-b-individual-skill-paths)
11+
- [Skill Directory Structure](#skill-directory-structure)
12+
- [SKILL.md Format](#skillmd-format)
13+
- [Frontmatter Fields](#frontmatter-fields)
14+
- [Body Content](#body-content)
15+
- [Creating a Skill](#creating-a-skill)
16+
- [How Skills Work at Runtime](#how-skills-work-at-runtime)
17+
- [Limitations](#limitations)
18+
- [Error Reference](#error-reference)
19+
- [References](#references)
20+
21+
---
22+
23+
# Introduction
24+
25+
Agent Skills allow product teams (e.g., RHEL Lightspeed, Ansible Lightspeed) to extend Lightspeed Core with specialized instructions and domain knowledge. Skills are packaged as portable directories following the [Agent Skills open standard](https://agentskills.io).
26+
27+
A skill is a `SKILL.md` file containing metadata and instructions that the LLM can load on demand. For example, a troubleshooting skill might contain step-by-step diagnostic procedures for a specific product, while a code review skill might contain a checklist and best practices.
28+
29+
> [!IMPORTANT]
30+
> Skills are configured by **product teams at deployment time**. End users of LS app products do not have the ability to add skills, similar to how they cannot add MCP servers.
31+
32+
# Configuration
33+
34+
Skills are configured in `lightspeed-stack.yaml` by specifying paths to skill directories. Two forms are supported.
35+
36+
## Option A: Directory of Skills
37+
38+
Point to a parent directory containing skill subdirectories. Each subdirectory with a `SKILL.md` file is loaded as a skill.
39+
40+
```yaml
41+
skills:
42+
paths:
43+
- "/var/skills/"
44+
```
45+
46+
This loads all skills found under `/var/skills/`:
47+
48+
```
49+
/var/skills/
50+
├── openshift-troubleshooting/
51+
│ ├── SKILL.md
52+
│ └── references/
53+
│ └── common-errors.md
54+
├── code-review/
55+
│ └── SKILL.md
56+
└── ansible-playbooks/
57+
├── SKILL.md
58+
└── references/
59+
└── module-reference.md
60+
```
61+
62+
## Option B: Individual Skill Paths
63+
64+
Point directly to specific skill directories for fine-grained control over which skills are loaded.
65+
66+
```yaml
67+
skills:
68+
paths:
69+
- "/var/skills/openshift-troubleshooting/"
70+
- "/var/skills/code-review/"
71+
```
72+
73+
> [!TIP]
74+
> Option A is recommended for most deployments. Use Option B when you need to selectively include specific skills from a larger collection.
75+
76+
See [examples/lightspeed-stack-skills.yaml](../examples/lightspeed-stack-skills.yaml) for a complete configuration example.
77+
78+
# Skill Directory Structure
79+
80+
Each skill is a directory containing, at minimum, a `SKILL.md` file:
81+
82+
```
83+
skill-name/
84+
├── SKILL.md # Required: metadata + instructions
85+
└── references/ # Optional: additional documentation
86+
├── guide.md
87+
└── troubleshooting.md
88+
```
89+
90+
- **`SKILL.md`** (required): Contains YAML frontmatter with metadata and Markdown body with instructions.
91+
- **`references/`** (optional): Contains additional documentation files that the LLM can load on demand when the skill instructions reference them.
92+
93+
> [!NOTE]
94+
> Script execution (`scripts/` subdirectory) is not supported. Only `SKILL.md` and `references/` files are used at runtime.
95+
96+
# SKILL.md Format
97+
98+
The `SKILL.md` file must contain YAML frontmatter (between `---` delimiters) followed by Markdown content.
99+
100+
## Frontmatter Fields
101+
102+
| Field | Required | Description |
103+
|-----------------|----------|-------------|
104+
| `name` | Yes | Skill identifier. Max 64 characters. Lowercase letters, numbers, and hyphens only. Must match the parent directory name. |
105+
| `description` | Yes | What the skill does and when to use it. Max 1024 characters. |
106+
107+
### `name` rules
108+
109+
- 1-64 characters
110+
- Lowercase letters (`a-z`), numbers (`0-9`), and hyphens (`-`) only
111+
- Must not start or end with a hyphen
112+
- Must not contain consecutive hyphens (`--`)
113+
- Must match the parent directory name
114+
115+
**Valid names**: `openshift-troubleshooting`, `code-review`, `data-analysis`
116+
117+
**Invalid names**: `OpenShift-Troubleshooting` (uppercase), `-code-review` (starts with hyphen), `code--review` (consecutive hyphens)
118+
119+
### `description` guidance
120+
121+
The description should include both **what** the skill does and **when** to use it. Include specific keywords that help the LLM identify relevant tasks.
122+
123+
```yaml
124+
# Good: specific about what and when
125+
description: Diagnose and fix common OpenShift deployment issues including pod failures, networking problems, and resource constraints. Use when users report deployment failures or application issues on OpenShift.
126+
127+
# Poor: too vague
128+
description: Helps with OpenShift.
129+
```
130+
131+
## Body Content
132+
133+
The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps the LLM perform the task effectively.
134+
135+
Recommended sections:
136+
- Step-by-step instructions
137+
- Examples of inputs and outputs
138+
- Common edge cases and how to handle them
139+
140+
> [!TIP]
141+
> Keep `SKILL.md` under 500 lines. Move detailed reference material to files in the `references/` subdirectory and reference them from the main instructions.
142+
143+
# Creating a Skill
144+
145+
Follow these steps to create a new skill:
146+
147+
**1. Create the skill directory**
148+
149+
The directory name must match the `name` field in `SKILL.md`.
150+
151+
```bash
152+
mkdir -p /var/skills/my-skill
153+
```
154+
155+
**2. Create the `SKILL.md` file**
156+
157+
```markdown
158+
---
159+
name: my-skill
160+
description: A brief description of what this skill does and when to use it.
161+
---
162+
163+
# My Skill
164+
165+
## When to use this skill
166+
167+
Use this skill when:
168+
- Condition A applies
169+
- The user asks about topic B
170+
171+
## Instructions
172+
173+
1. First, do X
174+
2. Then check Y
175+
3. If Z occurs, see [the reference guide](references/guide.md)
176+
```
177+
178+
**3. (Optional) Add reference files**
179+
180+
```bash
181+
mkdir -p /var/skills/my-skill/references
182+
```
183+
184+
Add documentation files that the skill instructions reference:
185+
186+
```markdown
187+
# references/guide.md
188+
189+
Detailed reference content goes here...
190+
```
191+
192+
**4. Add the skill path to configuration**
193+
194+
Add the path to your `lightspeed-stack.yaml`:
195+
196+
```yaml
197+
skills:
198+
paths:
199+
- "/var/skills/" # If using a directory of skills
200+
```
201+
202+
**5. Restart the service**
203+
204+
Skills are loaded at startup. Restart Lightspeed Core Stack to pick up new or modified skills.
205+
206+
See [examples/skills/](../examples/skills/) for complete working examples.
207+
208+
# How Skills Work at Runtime
209+
210+
Skills use a progressive disclosure pattern with three LLM tools:
211+
212+
1. **`list_skills`** — The LLM calls this to discover available skills. Returns the name and description of each skill.
213+
2. **`activate_skill`** — When a task matches a skill's description, the LLM calls this to load the full instructions from `SKILL.md`.
214+
3. **`load_skill_resource`** — If the skill instructions reference files in `references/`, the LLM calls this to load them on demand.
215+
216+
```
217+
User question
218+
│
219+
▼
220+
LLM calls list_skills → sees skill catalog (name + description)
221+
│
222+
▼ (if task matches a skill)
223+
LLM calls activate_skill → loads full SKILL.md instructions
224+
│
225+
▼ (if instructions reference a file)
226+
LLM calls load_skill_resource → loads file from references/
227+
│
228+
▼
229+
LLM follows skill instructions to answer
230+
```
231+
232+
The system prompt contains behavioral instructions telling the LLM how to use these tools. When no skills are configured, the tools and instructions are omitted entirely.
233+
234+
> [!NOTE]
235+
> Skills are tracked per conversation. If a skill is already loaded in a conversation, re-activating it returns a note instead of re-injecting the content.
236+
237+
# Limitations
238+
239+
- **No script execution**: The `scripts/` subdirectory from the agentskills.io spec is not supported. Skills provide instructions only; they do not execute code.
240+
- **Read-only**: Skills are loaded from the filesystem at startup and are read-only at runtime.
241+
- **No remote loading**: Skills must be present on the local filesystem. Loading from URLs or registries is not supported.
242+
- **Duplicate names**: Skill names must be unique across all configured paths. Duplicate names cause a startup error.
243+
244+
# References
245+
246+
- [Agent Skills Specification](https://agentskills.io/specification) — the open standard for skill format
247+
- [Agent Skills Implementation Guide](https://agentskills.io/client-implementation/adding-skills-support) — client implementation guidance
248+
- [Feature Design Document](design/agent-skills/agent-skills.md) — internal design spec for the Lightspeed Core implementation
249+
- [Example Skills](../examples/skills/) — working example skills
250+
- [Example Configuration](../examples/lightspeed-stack-skills.yaml) — example `lightspeed-stack.yaml` with skills configured

‎examples/lightspeed-stack-skills.yaml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Lightspeed Core Service (LCS)
2+
service:
3+
host: localhost
4+
port: 8080
5+
auth_enabled: false
6+
workers: 1
7+
color_log: true
8+
access_log: true
9+
llama_stack:
10+
use_as_library_client: false
11+
url: http://localhost:8321
12+
api_key: xyzzy
13+
user_data_collection:
14+
feedback_enabled: true
15+
feedback_storage: "/tmp/data/feedback"
16+
transcripts_enabled: true
17+
transcripts_storage: "/tmp/data/transcripts"
18+
authentication:
19+
module: "noop"
20+
# Agent Skills configuration
21+
# Skills provide domain-specific instructions that the LLM can load on demand.
22+
# Each path points to either:
23+
# - A directory containing a SKILL.md file (single skill)
24+
# - A directory containing subdirectories with SKILL.md files (multiple skills)
25+
skills:
26+
paths:
27+
- "/var/skills/" # Directory containing skill subdirectories
28+
# Alternative: specify individual skill paths for fine-grained control
29+
# skills:
30+
# paths:
31+
# - "/var/skills/openshift-troubleshooting/"
32+
# - "/var/skills/code-review/"

0 commit comments

Comments
 (0)