RHIDP-15891: add /v1/skills endpoint

README.md

@@ -1248,6 +1248,57 @@ will be returned.
 }
 ```
 
+## Skills endpoint
+
+**Endpoint:** `GET /v1/skills`
+
+Process GET requests and return the list of agent skills loaded from the
+directories configured under `skills.paths` in the service configuration
+(see [Agent Skills](#agent-skills) and the [Agent Skills Guide](docs/user_doc/skills_guide.md)
+for configuration and authoring instructions). Each skill's name and
+description are read from its `SKILL.md` frontmatter.
+
+This endpoint reads the configured skill directories directly and does not
+invoke an LLM or agent — it is intended for clients (e.g. the RHDH UI or
+other tooling) that need a deterministic way to introspect configured
+skills without the cost, latency, or non-determinism of an LLM tool call.
+This is distinct from the `list_skills` tool that the agent itself may
+invoke during a `/v1/query` or `/v1/streaming_query` turn.
+
+If [authentication](#authentication) is enabled, include the appropriate
+credentials (e.g. `-H "Authorization: Bearer <token>"`); otherwise the
+request returns `401`/`403`.
+
+```bash
+curl http://localhost:8080/v1/skills
+```
+
+**Response Body:**
+
+```json
+{
+  "skills": [
+    {
+      "name": "code-review",
+      "description": "Review code for quality and security"
+    },
+    {
+      "name": "openshift-troubleshooting",
+      "description": "Troubleshoot OpenShift cluster issues"
+    }
+  ]
+}
+```
+
+If no skills are configured (or `skills.paths` is empty), the endpoint
+returns an empty list:
+
+```json
+{
+  "skills": []
+}
+```
+
 
 # Database structure
 

docs/devel_doc/ARCHITECTURE.md

@@ -503,6 +503,10 @@ This section documents the REST API endpoints exposed by LCore for client intera
 **List Shields:** `GET /shields`
 - Returns available guardrails
 
+**List Skills:** `GET /skills`
+- Returns loaded agent skills (name and description) from the configured
+  skill directories, without requiring an LLM/agent turn
+
 **List RAG Databases:** `GET /rags`
 - Returns configured vector stores
 

docs/devel_doc/openapi.json

@@ -1671,6 +1671,156 @@
                 }
             }
         },
+        "/v1/skills": {
+            "get": {
+                "tags": [
+                    "skills"
+                ],
+                "summary": "Skills Endpoint Handler",
+                "description": "Handle requests to the /skills endpoint.\n\nProcess GET requests to the /skills endpoint, returning a list of loaded\nagent skills with their metadata (name, description).\n\n### Parameters:\n- request: The incoming HTTP request (used by middleware).\n- auth: Authentication tuple from the auth dependency (used by middleware).\n\n### Raises:\n- HTTPException: with status 401 for unauthorized access.\n- HTTPException: with status 403 if permission is denied.\n- HTTPException: with status 500 and a detail object containing `response`\n  and `cause` when service configuration is wrong or incomplete.\n\n### Returns:\n- SkillsResponse: An object containing the list of loaded skills.",
+                "operationId": "skills_endpoint_handler_v1_skills_get",
+                "responses": {
+                    "200": {
+                        "description": "Successful response",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/SkillsResponse"
+                                },
+                                "example": {
+                                    "skills": [
+                                        {
+                                            "description": "Review code for quality and security",
+                                            "name": "code-review"
+                                        },
+                                        {
+                                            "description": "Troubleshoot OpenShift cluster issues",
+                                            "name": "openshift-troubleshooting"
+                                        }
+                                    ]
+                                }
+                            }
+                        }
+                    },
+                    "401": {
+                        "description": "Unauthorized",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/UnauthorizedResponse"
+                                },
+                                "examples": {
+                                    "missing header": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "No Authorization header found",
+                                                "response": "Missing or invalid credentials provided by client"
+                                            }
+                                        }
+                                    },
+                                    "missing token": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "No token found in Authorization header",
+                                                "response": "Missing or invalid credentials provided by client"
+                                            }
+                                        }
+                                    },
+                                    "expired token": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "Token has expired",
+                                                "response": "Missing or invalid credentials provided by client"
+                                            }
+                                        }
+                                    },
+                                    "invalid signature": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "Invalid token signature",
+                                                "response": "Missing or invalid credentials provided by client"
+                                            }
+                                        }
+                                    },
+                                    "invalid key": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "Token signed by unknown key",
+                                                "response": "Missing or invalid credentials provided by client"
+                                            }
+                                        }
+                                    },
+                                    "missing claim": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "Token missing claim: user_id",
+                                                "response": "Missing or invalid credentials provided by client"
+                                            }
+                                        }
+                                    },
+                                    "invalid k8s token": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "Invalid or expired Kubernetes token",
+                                                "response": "Missing or invalid credentials provided by client"
+                                            }
+                                        }
+                                    },
+                                    "invalid jwk token": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "Authentication key server returned invalid data",
+                                                "response": "Missing or invalid credentials provided by client"
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "403": {
+                        "description": "Permission denied",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/ForbiddenResponse"
+                                },
+                                "examples": {
+                                    "endpoint": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "User 6789 is not authorized to access this endpoint.",
+                                                "response": "User does not have permission to access this endpoint"
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "500": {
+                        "description": "Internal server error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/InternalServerErrorResponse"
+                                },
+                                "examples": {
+                                    "configuration": {
+                                        "value": {
+                                            "detail": {
+                                                "cause": "Lightspeed Stack configuration has not been initialized.",
+                                                "response": "Configuration is not loaded"
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "/v1/providers": {
             "get": {
                 "tags": [
@@ -11655,6 +11805,7 @@
                     "feedback",
                     "get_models",
                     "get_tools",
+                    "get_skills",
                     "get_shields",
                     "list_providers",
                     "get_provider",
@@ -20834,6 +20985,27 @@
                     }
                 ]
             },
+            "SkillMetadata": {
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "title": "Name",
+                        "description": "Unique name of the skill"
+                    },
+                    "description": {
+                        "type": "string",
+                        "title": "Description",
+                        "description": "Human readable description of what the skill does"
+                    }
+                },
+                "type": "object",
+                "required": [
+                    "name",
+                    "description"
+                ],
+                "title": "SkillMetadata",
+                "description": "Metadata describing a single loaded agent skill.\n\nAttributes:\n    name: Unique name of the skill.\n    description: Human readable description of what the skill does."
+            },
             "SkillsConfiguration": {
                 "properties": {
                     "paths": {
@@ -20851,6 +21023,38 @@
                 "title": "SkillsConfiguration",
                 "description": "Agent skills configuration.\n\nSpecifies paths to skill directories. Skill metadata (name, description)\nis read from SKILL.md frontmatter at startup.\n\nEach path can point to either:\n- A directory containing a SKILL.md file (single skill)\n- A directory containing subdirectories with SKILL.md files (multiple skills)\n\nPaths are validated at startup to ensure they exist and contain valid SKILL.md files."
             },
+            "SkillsResponse": {
+                "properties": {
+                    "skills": {
+                        "items": {
+                            "$ref": "#/components/schemas/SkillMetadata"
+                        },
+                        "type": "array",
+                        "title": "Skills",
+                        "description": "List of loaded skills with metadata"
+                    }
+                },
+                "type": "object",
+                "required": [
+                    "skills"
+                ],
+                "title": "SkillsResponse",
+                "description": "Model representing a response to skills request.\n\nAttributes:\n    skills: List of loaded skills with metadata (name and description).",
+                "examples": [
+                    {
+                        "skills": [
+                            {
+                                "description": "Review code for quality and security",
+                                "name": "code-review"
+                            },
+                            {
+                                "description": "Troubleshoot OpenShift cluster issues",
+                                "name": "openshift-troubleshooting"
+                            }
+                        ]
+                    }
+                ]
+            },
             "SolrVectorSearchRequest": {
                 "properties": {
                     "mode": {
@@ -22431,6 +22635,10 @@
             "name": "shields",
             "description": "Safety shields."
         },
+        {
+            "name": "skills",
+            "description": "Agent skills."
+        },
         {
             "name": "streaming_query",
             "description": "Streaming query (SSE)."

docs/models/successful_responses.md

@@ -2305,6 +2305,22 @@ Model representing a response to shields request.
 | shields | array | List of shields available |
 
 
+## SkillMetadata
+
+
+Metadata describing a single loaded agent skill.
+
+Attributes:
+    name: Unique name of the skill.
+    description: Human readable description of what the skill does.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| name | string | Unique name of the skill |
+| description | string | Human readable description of what the skill does |
+
+
 ## SkillsConfiguration
 
 
@@ -2325,6 +2341,17 @@ Paths are validated at startup to ensure they exist and contain valid SKILL.md f
 | paths | array | Paths to skill directories or directories containing skill subdirectories. |
 
 
+## SkillsResponse
+
+
+Model representing a response to skills request.
+
+
+| Field | Type | Description |
+|-------|------|-------------|
+| skills | array | List of loaded skills with metadata |
+
+
 ## SplunkConfiguration