Skill-templates

.github/ISSUE_TEMPLATE/codebundle-wanted.yaml

@@ -1,5 +1,5 @@
-name: CodeBundle Wanted
-description: Request a new CodeBundle from the Community
+name: Skill Template Wanted
+description: Request a new Skill Template (formerly "CodeBundle") from the community
 title: "[new-codebundle-request] - "
 labels: [new-codebundle-request"] 
 assignees: 
@@ -8,39 +8,41 @@ body:
   - type: markdown
     attributes:
       value: |
-        Hello there 🎉! We're excited that you want RunWhen's libraries to expand. Your request for a contribution will make a big difference in improving the community's experience with Kubernetes and cloud environments. Feel free to add as much or as little detail below. 
-        
+        Hello there 🎉! We're excited that you want RunWhen's libraries to expand. Your request for a contribution will make a big difference in improving the community's experience with Kubernetes and cloud environments. Feel free to add as much or as little detail below.
+
         Each and every request is highly appreciated! Let's make navigating complex environments easier together!
-
+
+        > **Heads up — terminology:** a **Skill Template** is what we used to call a **CodeBundle** (a reusable package of automation Tools). A **Tool** is what we used to call a **Task** — Runbooks run on demand, Monitors run on a schedule. Issue title prefix `[new-codebundle-request]` and label `new-codebundle-request` are kept for backward compatibility with existing workflows.
+
         If you're open to being contacted with follow-up questions, please place an [x] beside 'yes, please' at the end of the form. 😊
 
   - type: textarea
     id: codebundle-request
     attributes:
       label: What cloud platform(s) should this support?
-      description: Please describe, as best as you can, what this CodeBundle should do - including which cloud resources it should interact with. 
+      description: Please describe, as best as you can, what this Skill Template should do - including which cloud resources it should interact with. 
       placeholder: ex. Kubernetes on Azure (AKS)
     validations:
       required: true
 
   - type: textarea
     id: task-titles
     attributes:
-      label: What are some key tasks that should be performed?
-      description: Please outline a 3-7 key tasks that should be automated, along with any issues that should be raised if the result is not "healthy".
+      label: What are some key Tools (Runbooks / Monitors) that should be performed?
+      description: Please outline 3-7 key Tools that should be automated, along with any issues that should be raised if the result is not "healthy".
       placeholder: | 
         ex. 
-        1. Trace Namespace Errors - Raise issue if Warning or Error events in last 10 minutes
-        2. Fetch Unready Pods - Raise issue if more than 0 pods are unready
-        3. List all Namespace Resources and Add to Report
+        1. Trace Namespace Errors (Runbook) - Raise issue if Warning or Error events in last 10 minutes
+        2. Fetch Unready Pods (Runbook) - Raise issue if more than 0 pods are unready
+        3. List all Namespace Resources and Add to Report (Runbook)
     validations:
       required: true
 
   - type: textarea
     id: additional-context
     attributes:
       label: Any other helpful context?
-      description: Provide any additional context surrounding this Codebundle, such as specific circumstances or dependencies that make it particularly useful.
+      description: Provide any additional context surrounding this Skill Template, such as specific circumstances or dependencies that make it particularly useful.
       placeholder: ex. We run a multi-cluster istio setup, so it's important to support multiple contexts/clusters. 
     validations:
       required: false
@@ -58,4 +60,4 @@ body:
   - type: markdown
     attributes:
       value: |
-        You're done🎉! Woohoo! Thanks for taking the time to share your troubleshooting needs with the community! We appreciate your request!
+        You're done🎉! Woohoo! Thanks for taking the time to share your troubleshooting needs with the community! We appreciate your request!

Agents.md

@@ -1,4 +1,25 @@
-# AI Agent Guidelines for CodeCollection Registry
+# AI Agent Guidelines for RunWhen Skills Registry
+
+Note: the directory and repo retain the legacy `codecollection-registry` identifier for path/URL stability. The product itself is now branded **RunWhen Skills Registry**.
+
+## 🗣️ Terminology (2026 — read this first)
+
+The registry uses **two parallel vocabularies**:
+
+| Internal (unchanged) | New display name |
+|---|---|
+| `Task` (registry concept) | **Tool** |
+| `CodeBundle` | **Skill Template** (registry artifact — vars/secrets unresolved) |
+| (no internal equivalent — runtime only) | **Skill** (runtime instantiation of a Skill Template inside a workspace; also used colloquially as the umbrella term in page titles like "All Skills") |
+| `SLI` (`type: "SLI"`) | **Monitor** — Tool that runs on a schedule, emits 0–1 numeric value |
+| `TaskSet` (`type: "TaskSet"`) | **Runbook** — Tool that runs on demand, emits structured findings |
+| `CodeCollection` | **CodeCollection** (unchanged) |
+
+A workspace **renders** a Skill Template into a Skill at runtime (vars + secrets substituted in). The registry only ever stores Skill Templates; Skills only exist inside workspaces.
+
+Use the **new vocabulary** in all user-facing surfaces (UI, MCP markdown output, chat replies, docs). Leave internal identifiers (DB columns, JSON `type` enums, MCP tool function names like `find_codebundle`, API paths like `/api/v1/codebundles`) as-is for backward compatibility. Canonical mapping table and "where each vocabulary applies" matrix live in [`cc-registry-v2/AGENTS.md`](cc-registry-v2/AGENTS.md#terminology).
+
+---
 
 ## 📋 General Rules
 
@@ -66,7 +87,7 @@ codecollection-registry/
 
 ## 🏗️ Project Structure
 
-### CodeCollection Registry v2 Architecture
+### RunWhen Skills Registry v2 Architecture
 
 ```
 codecollection-registry/
@@ -316,7 +337,7 @@ POST /api/v1/chat/query
 4. ❌ Don't commit `az.secret` or other credential files
 5. ❌ Don't run database operations in request handlers (use Celery tasks)
 6. ❌ Don't show raw database IDs in UI (use slugs)
-7. ❌ Don't mix terminology (use CodeCollections, CodeBundles, Tasks - not "code bundles", "bundles", etc.)
+7. ❌ Don't mix vocabularies in display copy. Use the new vocabulary (Skill Templates, Tools, Monitors, Runbooks) in **all user-facing surfaces** — UI labels, MCP markdown output, chat replies, docs. Internal identifiers (DB columns `tasks`/`slis`, JSON `type: "TaskSet" | "SLI" | "CodeBundle"`, MCP tool function names like `find_codebundle`, API paths `/api/v1/codebundles`) stay as legacy names for backward compatibility. See `cc-registry-v2/AGENTS.md` § Terminology for the full mapping table.
 
 ---
 

README.md

@@ -1,6 +1,8 @@
-# CodeCollection Registry
+# RunWhen Skills Registry
 
-A registry for RunWhen CodeCollections -- browsing, searching, and configuring automation CodeBundles.
+A registry of safe-for-production Skills for AI agents -- browsing, searching, and configuring Skill Templates (formerly "CodeBundles") backed by RunWhen CodeCollections.
+
+> Note: the GitHub repo retains the legacy `codecollection-registry` name for URL stability. The product is **RunWhen Skills Registry**.
 
 ## Repository Structure
 
@@ -27,7 +29,7 @@ See [cc-registry-v2/README.md](cc-registry-v2/README.md) for setup, configuratio
 
 ### [mcp-server/](mcp-server/) -- MCP Server
 
-A standalone FastAPI server that exposes MCP tools for querying the CodeCollection Registry. Delegates all data access to the backend API. Includes an offline indexer for generating vector embeddings.
+A standalone FastAPI server that exposes MCP tools for querying the RunWhen Skills Registry. Delegates all data access to the backend API. Includes an offline indexer for generating vector embeddings.
 
 ```bash
 cd mcp-server/

cc-registry-v2/.gitignore

@@ -70,6 +70,13 @@ frontend/.env.development.local
 frontend/.env.test.local
 frontend/.env.production.local
 
+# The bare `lib/` and `lib64/` rules above (Python setuptools build dirs)
+# are unanchored, so they accidentally match `frontend/src/lib/`. Un-ignore
+# the frontend source tree explicitly. Anything we add under
+# `frontend/src/lib/` (e.g. terminology.ts) must be committed.
+!frontend/src/lib/
+!frontend/src/lib/**
+
 # Testing
 .coverage
 .pytest_cache/

cc-registry-v2/AGENTS.md

@@ -1,12 +1,14 @@
-# AGENTS.md — CodeCollection Registry v2
+# AGENTS.md — RunWhen Skills Registry v2
 
 Instructions for AI coding agents working in this codebase.
 
+Note: the directory name (`cc-registry-v2`) and GitHub repo (`codecollection-registry`) retain the legacy "codecollection" identifier for path/URL stability. The product itself is now branded **RunWhen Skills Registry**.
+
 ---
 
 ## Project Overview
 
-The CodeCollection Registry is a public-facing web app for browsing, searching, and configuring RunWhen automation (CodeBundles). It consists of 8 Docker services:
+The RunWhen Skills Registry is a public-facing web app for browsing, searching, and configuring RunWhen automation (Skill Templates, formerly "CodeBundles"). It consists of 8 Docker services:
 
 | Service | Stack | Port | Purpose |
 |---------|-------|------|---------|
@@ -23,15 +25,48 @@ The CodeCollection Registry is a public-facing web app for browsing, searching,
 
 ## Terminology
 
-Use these exact terms — never abbreviate or paraphrase:
+The codecollection-registry uses **two parallel vocabularies**: a new user-facing vocabulary that aligns with industry/agent terminology, and a legacy internal vocabulary that remains in source code, JSON `type` enums, DB columns, MCP tool function names, and API paths. **All display surfaces — UI, MCP markdown output, chat replies, docs, GitHub issue templates — should use the new vocabulary.** Internal identifiers stay byte-identical for backward compatibility with existing integrations (workspace platform, MCP clients, runner, external scripts).
+
+### Vocabulary mapping (2026)
+
+| Internal name (unchanged) | New display name | Behavioral definition |
+|---|---|---|
+| `Task` (registry concept) | **Tool** | Any invocable unit. Parent concept covering both sub-types. Maps to MCP/OpenAI/Anthropic "Tool". |
+| `CodeBundle` | **Skill Template** | Reusable, parameterizable package containing one or more Tools. Lives in the registry. Vars and secrets are unresolved placeholders. |
+| (no internal equivalent — runtime concept) | **Skill** | The runtime instantiation of a Skill Template inside a workspace, with vars/secrets materialized against real infrastructure. The registry itself never holds Skills — only Skill Templates. "Skill" is also used colloquially as the umbrella word in user-facing page titles (e.g. "All Skills") because it reads naturally and aligns with Anthropic Agent Skills / industry usage. |
+| `SLI` (`type: "SLI"`) | **Monitor** | A Tool that runs on a schedule, continuously, in the background. Emits a 0–1 numeric value. |
+| `TaskSet` (`type: "TaskSet"`) | **Runbook** | A Tool that is invoked on demand in response to an event or request. Emits structured findings with next-steps. |
+| `CodeCollection` | **CodeCollection** (unchanged) | Git-repo-level grouping of Skill Templates. |
+
+Tagline (for chat/docs/intro copy): *"A Skill Template packages Tools. Workspaces render Skill Templates into Skills at runtime. Monitors are Tools that run themselves on a schedule. Runbooks are Tools that run on demand."*
+
+#### Skill vs Skill Template — when to use which
+
+- Use **Skill Template** when referring to the registry-side artifact: search results, browse pages, "request a new Skill Template" copy, GitHub issue templates, OpenAPI descriptions, MCP markdown output that describes what the registry holds.
+- Use **Skill** when referring to the runtime/workspace artifact, or as the colloquial umbrella term in short page titles (e.g. "All Skills"). When in doubt in long-form copy, prefer **Skill Template** for precision.
+
+### Where each vocabulary applies
+
+| Surface | Vocabulary | Notes |
+|---|---|---|
+| React UI labels, page titles, badges, tabs, hero copy | **NEW** | Routed through `frontend/src/lib/terminology.ts` |
+| MCP server markdown output (`get_codebundle_details`, `find_codebundle`, etc.) | **NEW** | Strings are user-facing in chat clients |
+| Chat system prompt + LLM-generated replies | **NEW** (with legacy aliases) | System prompt teaches both vocabularies so legacy queries still resolve |
+| GitHub issue templates (`codebundle-wanted.yaml`) user-facing copy | **NEW** | "Request a Skill Template" |
+| Docs (`AGENTS.md`, `ARCHITECTURE.md`, `MCP_WORKFLOW.md`, `sources.yaml`, indexed glossaries) | **NEW** (with parenthetical legacy term on first mention) | Feeds chat indexing |
+| OpenAPI summaries/descriptions | **NEW** (with parenthetical legacy term) | Paths and schemas unchanged |
+| **MCP tool function names** (`find_codebundle`, `list_codebundles`, `search_codebundles`, `get_codebundle_details`, `request_codebundle`) | **LEGACY** | External AI integrations depend on these identifiers |
+| **API paths** (`/api/v1/codebundles`, `/api/v1/registry/tasks`, `/collections/{slug}/codebundles/{slug}`) | **LEGACY** | Client compatibility |
+| **DB tables/columns** (`codebundles`, `codecollections`, `vector_codebundles`, `tasks`, `slis`, `task_count`, `sli_count`, `task_index`, `sli_path`) | **LEGACY** | Schema stability; requires alembic migration to rename |
+| **JSON `type` enum values** (`"TaskSet"`, `"SLI"`, `"CodeBundle"`) | **LEGACY** | Frontend `TYPE_LABELS` maps these to display names at render time |
+| Python class names, TypeScript interface names, route paths | **LEGACY** | Internal-only |
+
+### Other unchanged terms
 
-- **CodeCollection** — a git repo containing multiple CodeBundles
-- **CodeBundle** — a folder within a CodeCollection containing automation tasks
-- **Task** — an individual automation script (either `TaskSet` or `SLI` type)
 - **RunWhen Platform** — the orchestration platform (not "RunWhen Core")
 - **Workspace Chat** — the AI chat feature (not "AI Chat" or "Eager Edgar Chat")
-- **Support Tags** — metadata tags on CodeBundles (e.g., `kubernetes`, `aws`, `azure`)
-- **Data Tags** — per-task data classification tags (`data:config`, `data:logs-regexp`, etc.)
+- **Support Tags** — metadata tags on Skill Templates (e.g., `kubernetes`, `aws`, `azure`)
+- **Data Tags** — per-Tool data classification tags (`data:config`, `data:logs-regexp`, etc.)
 
 ---
 

cc-registry-v2/README.md

@@ -1,6 +1,8 @@
-# CodeCollection Registry v2 - Microservices Architecture
+# RunWhen Skills Registry v2 - Microservices Architecture
 
-A modern, scalable registry for RunWhen CodeCollections with AI-powered enhancement capabilities.
+A modern, scalable registry of safe-for-production Skills (Skill Templates and Tools) for AI agents, with AI-powered enhancement capabilities.
+
+> Note: the directory name (`cc-registry-v2`) retains the legacy "codecollection" identifier for path stability. The product is **RunWhen Skills Registry**.
 
 ## Architecture Overview
 

cc-registry-v2/backend/app/core/config.py

@@ -68,7 +68,7 @@ class Settings(BaseSettings):
 
     # API Settings
     API_V1_STR: str = "/api/v1"
-    PROJECT_NAME: str = "CodeCollection Registry"
+    PROJECT_NAME: str = "RunWhen Skills Registry"
 
     # Config-file paths (codecollections.yaml, schedules.yaml, sources.yaml).
     #

cc-registry-v2/backend/app/main.py

@@ -26,7 +26,7 @@
 # /docs against a local-only backend; update bookmarks to /api/docs.
 app = FastAPI(
     title=settings.PROJECT_NAME,
-    description="Interactive CodeCollection Registry API — see /api/openapi.yaml for the full spec.",
+    description="Interactive RunWhen Skills Registry API — see /api/openapi.yaml for the full spec.",
     version="2.0.0",
     docs_url="/api/docs",
     redoc_url="/api/redoc",
@@ -78,7 +78,7 @@ async def openapi_yaml():
 async def root():
     """Root endpoint"""
     return {
-        "message": "CodeCollection Registry API",
+        "message": "RunWhen Skills Registry API",
         "version": "2.0.0",
         "docs": "/api/docs",
         "redoc": "/api/redoc",
@@ -263,7 +263,12 @@ async def get_all_tasks(
     limit: int = 100,
     offset: int = 0
 ):
-    """Get all tasks with filtering and pagination"""
+    """Search Tools (formerly "tasks") across all Skill Templates (codebundles) with filtering and pagination.
+
+    The path `/api/v1/registry/tasks` and the JSON field `tasks[]` are kept for backward
+    compatibility. Each returned item carries a `type` field of `"TaskSet"` (Runbook) or
+    `"SLI"` (Monitor). User-facing surfaces (UI, MCP markdown, chat) map these to the
+    new vocabulary (Skill Template, Tool, Runbook, Monitor)."""
     try:
         from app.core.database import SessionLocal
         from app.models import CodeCollection, Codebundle
@@ -274,7 +279,7 @@ async def get_all_tasks(
         try:
             from app.core.visibility import public_only
             # Build the query — always join CodeCollection so we can scope to
-            # public-visibility collections (hidden CCs and their codebundles
+            # public-visibility collections (hidden CCs and their Skill Templates
             # do not appear on the public registry website).
             query = (
                 db.query(Codebundle)
@@ -804,7 +809,9 @@ async def get_recent_codebundles():
 
 @app.get("/api/v1/registry/recent-tasks")
 async def get_recent_tasks():
-    """Get the 10 most recently added tasks based on git update date"""
+    """Get the 10 most recently added Tools (Runbooks / Monitors) based on git update date.
+
+    Path and response field names retained for backward compatibility; `tasks` → `Tools`."""
     try:
         from app.core.database import SessionLocal
         from app.models import CodeCollection, Codebundle

cc-registry-v2/backend/app/routers/github_issues.py

@@ -71,7 +71,7 @@ async def create_task_request_issue(request: TaskRequestIssue):
             "- [ ] Test the codebundle functionality",
             "",
             "---",
-            "*This issue was automatically created from the CodeCollection Registry chat interface.*"
+            "*This issue was automatically created from the RunWhen Skills Registry chat interface.*"
         ])
 
         body = "\n".join(body_parts)

cc-registry-v2/backend/app/routers/intake.py

@@ -315,7 +315,7 @@ def _build_minimal_issue_body(req: SubmitRequest) -> str:
 
     parts.extend([
         "---",
-        f"*Created via CodeCollection Registry intake at {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}.*",
+        f"*Created via RunWhen Skills Registry intake at {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}.*",
     ])
     return "\n".join(parts)