orq-ai · KarinaKKarinaK · May 14, 2026 · May 15, 2026 · May 15, 2026 · May 15, 2026
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "orq",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Agent skills for building, deploying, evaluating, and monitoring LLM pipelines on the orq.ai platform.",
   "author": {
     "name": "orq.ai",

diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "orq",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Agent skills for building, deploying, evaluating, and monitoring LLM pipelines on the orq.ai platform.",
   "author": {
     "name": "orq.ai",

diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "orq",
   "displayName": "orq.ai",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "Agent skills for building, deploying, evaluating, and monitoring LLM pipelines on the orq.ai platform.",
   "author": {
     "name": "orq.ai",

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.0] - 2026-05-14
+
+### Added
+- `manage-skills` skill — CRUD workflow for the orq.ai Skills entity (formerly Prompt Snippets), backed by `/v2/skills`. Covers list, get, create, update, soft-disable (`enabled: false`), and delete via the `*_skill` MCP tools. Includes authoring guidance (`display_name`, `description`, `tags`, `project_id`, `path`, `enabled`) and disambiguates the platform Skill entity from this repo's code-assistant Orq Skills and from the unrelated A2A `AgentCard.skills` array.
+- `manage-skills`: documents the `{{snippet.<display_name>}}` template placeholder as the only mechanism for consuming Skills inside prompts and agent instructions (the `snippet.` prefix is a backwards-compat holdover from the rename — there is no `{{skill.<...>}}` syntax).
+- `manage-skills`: reference-scan-before-delete workflow — paginates `search_entities`, fetches each candidate's body with `get_deployment` / `get_agent` / `get_skill`, and substring-matches `{{snippet.<display_name>}}` to surface consumers before any destructive operation. Defaults to `enabled: false` (soft disable) when references are found.
+- `manage-skills`: rename-breaks-references warning on `display_name` updates — runs the same reference scan before any rename and offers to fan out updates in the same session.
+- `manage-skills`: documents `GET /v2/skills` cursor pagination (`limit` / `starting_after` / `ending_before`) and the lack of server-side filters; pushes `project_id` / `tags` / `display_name` filtering to the client.
+- `manage-skills`: anti-pattern guidance against `+NEVER+` / "you MUST refuse" prose constraints in `instructions` — recommends MCP tool gates for hard guardrails.
+- `manage-skills`: error-handling guidance for `create_skill` `AlreadyExists` (offers either a renamed create or `update_skill` against the existing Skill).
+- `/manage-skills` slash command — routes to list / get / create / update / disable / delete phases.
+
 ## [0.0.2] - 2026-04-21
 
 ### Added

diff --git a/README.md b/README.md
@@ -171,6 +171,7 @@ Skills are triggered by describing what you need. Claude picks the right skill a
 | **compare-agents** | Run cross-framework agent comparisons using evaluatorq — compare orq.ai, LangGraph, CrewAI, OpenAI Agents SDK, and others | [SKILL.md](skills/compare-agents/SKILL.md) |
 | **generate-synthetic-dataset** | Generate and curate evaluation datasets — structured generation, quick from description, expansion, and dataset maintenance | [SKILL.md](skills/generate-synthetic-dataset/SKILL.md) |
 | **optimize-prompt** | Analyze and optimize system prompts using a structured prompting guidelines framework | [SKILL.md](skills/optimize-prompt/SKILL.md) |
+| **manage-skills** | Manage orq.ai Skills (the platform entity) — list/get/create/update/delete, authoring guidance, governance (`agent.skills[]` wiring), and platform-caveat workarounds | [SKILL.md](skills/manage-skills/SKILL.md) |
 <!-- END_SKILLS_TABLE -->
 
 ---

diff --git a/agents/AGENTS.md b/agents/AGENTS.md
@@ -14,6 +14,7 @@ These skills are:
  - compare-agents -> "skills/compare-agents/SKILL.md"
  - generate-synthetic-dataset -> "skills/generate-synthetic-dataset/SKILL.md"
  - invoke-deployment -> "skills/invoke-deployment/SKILL.md"
+ - manage-skills -> "skills/manage-skills/SKILL.md"
  - optimize-prompt -> "skills/optimize-prompt/SKILL.md"
  - run-experiment -> "skills/run-experiment/SKILL.md"
  - setup-observability -> "skills/setup-observability/SKILL.md"
@@ -40,6 +41,8 @@ compare-agents: `Run cross-framework agent comparisons using evaluatorq — comp
 
 setup-observability: `Set up orq.ai observability for LLM applications — AI Router proxy, OpenTelemetry, tracing setup, and trace enrichment. Use when setting up tracing, adding the AI Router proxy, integrating OpenTelemetry, auditing existing instrumentation, or enriching traces with metadata. Do NOT use when traces already exist and you need to debug failures (use analyze-trace-failures).`
 
+manage-skills: `Manage orq.ai Skills (the platform entity, formerly Snippets — distinct from this repo's code-assistant skills) end-to-end: list, get, create, update, enable/disable, and delete Skills via the /v2/skills API. Covers authoring guidance (display_name, description, tags, project_id, path, enabled), how Skills get consumed via the {{snippet.<display_name>}} placeholder in prompts and agent instructions, the reference-scan-before-delete workflow, the rename-breaks-references warning, and the +NEVER+ prose anti-pattern. Use when the user wants to create, audit, edit, soft-disable, or retire orq.ai Skills.`
+
 </available_skills>
 
 Paths referenced within SKILL folders are relative to that SKILL. For example the build-evaluator `resources/judge-prompt-template.md` would be referenced as `skills/build-evaluator/resources/judge-prompt-template.md`.

diff --git a/commands/manage-skills.md b/commands/manage-skills.md
@@ -0,0 +1,45 @@
+---
+name: manage-skills
+description: Manage orq.ai Skills — list, get, create, update, disable, or delete Skills (the platform entity, formerly Snippets) and find the prompts/agents that reference them
+argument-hint: [list|get|create|update|disable|delete] [name-or-id]
+allowed-tools: AskUserQuestion, mcp__orq-workspace__list_skills, mcp__orq-workspace__get_skill, mcp__orq-workspace__create_skill, mcp__orq-workspace__update_skill, mcp__orq-workspace__delete_skill, mcp__orq-workspace__search_entities, mcp__orq-workspace__get_deployment, mcp__orq-workspace__get_agent
+---
+
+# Manage Skills
+
+Quick entry point into the `manage-skills` skill. Routes to the right phase based on the first argument, or asks if no argument is given.
+
+## Instructions
+
+### 1. Parse arguments
+
+`$ARGUMENTS` may contain an action and optionally a Skill `display_name` or `skill_id`:
+
+- `list` — Phase 1 (list / audit)
+- `get <name-or-id>` — Phase 2 (inspect a Skill)
+- `create` — Phase 3 (create a new Skill)
+- `update <name-or-id>` — Phase 4 (edit, including `enabled` / `display_name` / `instructions`)
+- `disable <name-or-id>` — Phase 4 shortcut: flip `enabled: false` (soft-retire)
+- `delete <name-or-id>` — Phase 5 (reference scan + delete)
+
+If `$ARGUMENTS` is empty, ask the user which action they want via `AskUserQuestion` and offer the six choices above.
+
+If `$ARGUMENTS` contains an action that requires a name/id but none was provided (e.g., `get`, `update`, `disable`, `delete`), call `list_skills` first and ask the user to pick.
+
+### 2. Delegate to `manage-skills`
+
+Read `skills/manage-skills/SKILL.md` and execute the matching phase. Pass the parsed name/id along.
+
+### 3. Safety rails
+
+- **Never** auto-execute `delete_skill` from this command — always route through Phase 5's reference-scan + warn-then-confirm flow.
+- **Always** offer `enabled: false` (soft disable) as the default first step when the reference scan finds consumers.
+- **Always** confirm project scope before `create_skill`.
+- **Always** warn before sending a `display_name` rename — it silently breaks every `{{snippet.<old-name>}}` reference.
+
+### 4. Error handling
+
+- **Auth errors** — "Authentication failed. Check that your `ORQ_API_KEY` is valid."
+- **`AlreadyExists` on create** — surface the conflicting Skill (paginate `list_skills`, find by `display_name`) and offer either a renamed create or `update_skill` against the existing one.
+- **Skill-tool unavailable** — "The orq MCP server doesn't expose `*_skill` tools in this workspace. Falling back to REST `/v2/skills` — confirm before proceeding."
+- **MCP unreachable** — "Could not reach the orq.ai MCP server. Make sure it's configured: `claude mcp add --transport http orq-workspace https://my.orq.ai/v2/mcp --header 'Authorization: Bearer ${ORQ_API_KEY}'`"