spec: skills and workflows — discovery, installation, and usage (#1117)

Gkrumbach07 · Ambient Code Bot · Ambient Code Bot · commit 0347c6f49df5 · 2026-04-02T16:12:02.000-05:00
Defines the architecture for how skills, workflows, and agents work in
ACP.

**Core insight**: A workflow is just a prompt + a list of skill source
references. Skills are the atomic reusable unit. The manifest format is
the contract — ACP and local tooling are just consumers.

- **Workflows don't contain skills** — they reference them by Git URL +
path
- **Skills are always fetched from canonical sources** at load time, not
embedded copies
- **Workspace library != auto-inject** — installing to workspace makes
items available, not active. Users select what loads per session.
- **Same manifest works everywhere** — ACP runner, local `--add-dir`, a
`/load-workflow` meta-skill, or a Claude Code plugin
- **Layered loading** — workflow dependencies + user-selected extras +
live imports, all fed into `add_dirs`

1. **Core Concepts** — Skill, Workflow, Agent, Manifest Format
2. **Discovery** — Marketplace, scanning, catalog format
3. **Installation &amp; Configuration** — Workspace level, session level,
workflow builder, selection model
4. **Usage in Sessions** — Loading order, runtime management, metadata
5. **Local Usage** — Manual, load-workflow skill, Claude Code plugin
6. **Manifest Format** — Proposed YAML schema
7. **Open Questions** — Format, versioning, plugin compat, RHAI
alignment, security

Looking for feedback on:
- The manifest format (extend ambient.json vs new workflow.yaml?)
- The selection model (workspace library vs auto-inject)
- The Agent concept (persona + workflows + skills)
- RHAI alignment (RHAIRFE-1370)

---------

Co-authored-by: Ambient Code Bot &lt;bot@ambient-code.local&gt;
diff --git a/specs/skills-and-workflows.md b/specs/skills-and-workflows.md
@@ -2,7 +2,7 @@
 
 ## Summary
 
-A workflow is a `CLAUDE.md` prompt plus a list of sources in `ambient.json`. Skills are the atomic reusable unit. Everything installed is a source reference — the runner auto-detects what's inside. ACP automates the cloning and wiring. Locally, a `/load-workflow` skill or manual `--add-dir` does the same thing. The marketplace feature is behind a feature flag.
+A workflow is a `CLAUDE.md` prompt plus a list of sources in `ambient.json`. Skills are the atomic reusable unit. ACP automates the cloning and wiring. Locally, a `/load-workflow` skill or manual `--add-dir` does the same thing.
 
 ---
 
@@ -64,7 +64,7 @@ You are a systematic bug fixer. Follow these phases:
 ```
 
 Sources support two formats:
-- **Structured object**: `{"url": "...", "branch": "...", "path": "..."}` — works with any Git host, branch is explicit. Supports optional `tag` or `sha` field for pinning.
+- **Structured object**: `{"url": "...", "branch": "...", "path": "..."}` — works with any Git host, branch is explicit
 - **Single URL string**: `"https://github.com/org/repo/tree/main/path"` — auto-parsed, convenient for sharing
 
 Skills are the reusable atoms. Workflows are recipes. The same skill can appear in multiple workflows.
@@ -85,35 +85,27 @@ Multi-agent orchestration (research agent → writer agent → editor agent pipe
 
 ## Discovery
 
-Discovery is behind a feature flag.
-
 ### What
 
 A way to browse and find skills, workflows, and plugins from curated sources.
 
-### Discovery vs Runtime
-
-Plugins are a **discovery format only** — the marketplace reads `plugin.json` and `marketplace.json` to display what's available. But at runtime, there is no plugin concept. When a user installs something, it becomes a source reference. The runner clones it as a regular source and adds it to `add_dirs`. Claude finds the skills inside. No plugin hooks, MCP servers, or LSP servers from plugins at runtime.
-
-### Source Types (for discovery/browsing)
-
-The marketplace scanner must read these formats to display available items:
+### Source Types
 
-1. **Claude Code marketplace catalogs** — `marketplace.json` files listing plugins with their sources. The scanner reads plugin metadata to extract skills, commands, and agents for display.
+The scanner must support three types of sources:
 
-2. **Claude Code plugins** — directories with `.claude-plugin/plugin.json` containing `skills/`, `commands/`, `agents/`. The scanner reads `plugin.json` for metadata and scans the plugin's directories to list its contents. Plugin-specific features (hooks, MCP, LSP) are shown as metadata but not loaded at runtime.
+1. **Claude Code plugins** — directories with `.claude-plugin/plugin.json` containing `skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`. This is the primary format to follow and expect. Skills are namespaced as `plugin-name:skill-name`.
 
-3. **Standalone repos with `.claude/`** — any Git repo containing `.claude/skills/`, `.claude/commands/`, `.claude/agents/`. Also supports root-level `skills/`, `commands/`, `agents/` (registry layout).
+2. **Claude Code marketplace catalogs** — `marketplace.json` files listing plugins with their sources. Users could add the same marketplace from local Claude Code via `/plugin marketplace add`.
 
-4. **Catalog JSON** — `data.json` files (like ai-helpers) listing items with metadata. Normalized to the same display format.
+3. **Standalone repos with `.claude/`** — any Git repo containing `.claude/skills/`, `.claude/commands/`, `.claude/agents/`. Also supports root-level `skills/`, `commands/`, `agents/` (registry layout like ai-helpers).
 
 ### How
 
 A cluster-level ConfigMap (`marketplace-sources`) holds available registry sources. The Marketplace page in the ACP UI shows:
 
 - Browsable catalogs from each source with search and type filters
 - Compact card tiles with name, description, type badge
-- Detail panel on click showing extracted skills, commands, and agents inside the source — rendered readably, not as a raw file viewer
+- Detail panel on click with full description, source repo link
 - "Import Custom" to scan any Git URL and discover items
 - Direct one-click install to workspace
 
@@ -133,76 +125,58 @@ When given a Git URL (from marketplace or custom), the backend:
 
 ### Format Alignment
 
-We follow Claude Code's plugin and skill formats as the standard. The [Agent Skills](https://agentskills.io) open standard that Claude Code implements is the closest cross-tool specification.
+We follow Claude Code's plugin and skill formats as the standard. The [Agent Skills](https://agentskills.io) open standard that Claude Code implements is the closest cross-tool specification. Our catalog format normalizes to the same shape regardless of source type.
 
 ---
 
 ## Installation & Configuration
 
-### Everything is a Source Reference
-
-All installed items are source references — Git URLs pointing to repos containing skills or workflows. There is no type distinction in the data model. Whether the source is a plugin repo, a standalone skills repo, or a workflow — at runtime, the runner clones it and adds it to `add_dirs`. Claude discovers the skills inside. The plugin format is only relevant for marketplace browsing, not for runtime loading.
-
 ### Workspace Level
 
-Source references installed at the workspace level are stored in the ProjectSettings CR. These represent the workspace's **registry** — what's available to sessions.
-
-The registry is NOT auto-injected into every session. At session creation, users select which sources to load from the registry. The workflow they choose also pulls in its own dependencies from the `sources` array in `ambient.json`.
+Items installed at the workspace level are stored in the ProjectSettings CR (`spec.installedItems`). These represent the workspace's **library** — what's available, not what's auto-loaded into every session.
 
-Items can optionally be marked as "always add" — these load into every session by default. This is useful for org-wide standards or team-shared skills. (Needs further design discussion.)
+When creating a session, users select which installed items to include. The workflow they choose pulls in its own skill dependencies from the `sources` array in `ambient.json`.
 
 ### Session Level
 
-Sources can be added to a running session via the context panel:
+Skills can be added to a running session via the context panel:
 
 - "Import Skills" in the Add Context dropdown
 - Provide a Git URL + optional branch + path
-- Backend clones, scans, loads skills into discoverable locations
-- Claude discovers them via live change detection
+- Backend clones, scans, writes skill files to `/workspace/file-uploads/.claude/`
+- Claude discovers them via live change detection (already in `add_dirs`)
 - Persisted via S3 state-sync on session suspend/resume
 
-### Skill Storage in the Runner
-
-Each source gets its own directory at `/workspace/sources/{name}/`, added to the Claude Agent SDK as a separate `--add-dir`. Claude Code discovers `.claude/skills/`, `.claude/commands/`, `.claude/agents/` inside each add_dir automatically via its standard discovery mechanism.
-
-This mirrors how repos work (`/workspace/repos/{name}/`). Benefits:
-
-- **Clean separation** — each source is isolated, easy to see what came from where
-- **No conflicts** — two sources with a skill named `review` coexist in separate add_dirs
-- **Simple removal** — removing a source is `rm -rf /workspace/sources/{name}/`
-- **Standard mechanism** — `add_dirs` is exactly what Claude Code designed for external skill loading
-- **Persistence** — `/workspace/sources/` is backed up by state-sync alongside repos and file-uploads
-
-Writing into the project's `.claude/` directory would pollute the working directory and create ownership ambiguity (which source owns which skill?). Separate add_dirs avoids this entirely.
-
-The workspace's active workflow remains the `cwd`. Additional sources are supplementary add_dirs. Repos, sources, artifacts, and file-uploads each get their own add_dir — Claude discovers from all of them.
-
-Items marked "always add" in the workspace registry are pre-selected at session creation. Users can uncheck them. No magic auto-injection — explicit, visible, reversible.
+### Workflow Builder
 
-### Versioning
+A UI for composing workflows from standalone skills:
 
-Sources reference branches by default, which means sessions always get the latest version — providing auto-update behavior. For pinning, sources support optional `tag` or `sha` fields:
+- Select skills from the workspace library or browse marketplace
+- Each skill is a reference (source URL + path), not a copy
+- Write the workflow prompt as `CLAUDE.md`
+- Configure metadata in `ambient.json` (name, description, rubric)
+- The `sources` array is built from selected skills
+- Save as a workflow that can be:
+  - Stored in the workspace
+  - Exported as a Git repo
+  - Exported as a Claude Code plugin
 
-```json
-{"url": "https://github.com/org/skills.git", "branch": "main", "path": "assess", "sha": "a1b2c3d4"}
-```
-
-When a SHA is specified, the runner checks out that exact commit. When only a branch is specified, the runner clones the latest. This gives users the choice: use `branch` for auto-update, use `sha` or `tag` for stability.
+The key constraint: skills are never copied into the workflow. The `ambient.json` holds source references. At load time, the runner resolves dependencies and clones each source.
 
 ### How Selection Works
 
-The workspace registry is not auto-injected. Selection happens at session creation:
+The workspace library is not auto-injected. Selection happens at session creation:
 
 1. User picks a workflow (or "General chat" for none)
 2. The workflow's `ambient.json` `sources` array declares dependencies — those are auto-loaded
-3. User can add any number of additional sources from the workspace registry
-4. The session stores the workflow reference + any additional source references
+3. User can optionally add standalone skills from the workspace library
+4. The session CRD stores the workflow reference + any additional skill sources
 
 This means:
-- Installing 50 sources to the workspace doesn't bloat every session
+- Installing 50 skills to the workspace doesn't bloat every session
 - The workflow controls its own dependencies
 - Users can augment with extras per session
-- "Always add" items provide workspace-level defaults (needs further design)
+- Workspace-level "always-on" skills could be supported via a flag but are not the default
 
 ---
 
@@ -212,27 +186,37 @@ This means:
 
 When a session starts, sources are loaded in layers:
 
-1. **Workflow sources** — skills from the workflow's `ambient.json` `sources` array, cloned to `/workspace/sources/{name}/` and added to `add_dirs`
-2. **Additional sources** — extra sources the user selected at session creation, same mechanism
-3. **Live additions** — sources imported during the session via the context panel, cloned to `/workspace/sources/` on the fly
+1. **Workflow sources** — skills from the workflow's `ambient.json` `sources` array, cloned and added to `add_dirs`
+2. **Additional standalone sources** — extra skills the user selected at session creation
+3. **Live additions** — skills imported during the session via the context panel
 
-Each source directory contains `.claude/skills/`, `.claude/commands/`, `.claude/agents/` as appropriate. Claude Code discovers from all `add_dirs` automatically.
+All layers produce directories with `.claude/skills/`, `.claude/commands/`, `.claude/agents/` structure. Each directory is passed to the Claude Agent SDK as an `--add-dir`. Claude Code handles discovery from there.
 
-### Visualization
+The `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` env var is set so that `CLAUDE.md` files from add-dirs are also loaded.
 
-Users should be able to see what's loaded in a session — not as raw files, but as extracted, readable metadata:
+### Authentication for Sources
 
-**In the session context panel**: A dedicated Skills section shows all loaded skills, commands, and agents across all sources. Each item displays its name, type badge, and source. Expandable per source to see what came from where. Items can be removed individually.
+Private repos and authenticated services (MCP servers) use the existing workspace credential system. If the workspace has GitHub/GitLab integrations configured, private source repos are cloned using those credentials via the git credential helper. MCP sources that require auth and TLS are handled through workspace integration configuration. No new auth fields in the manifest.
 
-**In the marketplace**: Clicking a source shows a detail panel with all the skills, commands, and agents it contains — rendered with descriptions and metadata, not as a file tree.
+### Runtime Management
 
-### Authentication for Sources
+The session context panel shows:
 
-Private repos and authenticated services (MCP servers) use the existing workspace credential system. If the workspace has GitHub/GitLab integrations configured, private source repos are cloned using those credentials via the git credential helper. MCP sources that require auth and TLS are handled through workspace integration configuration. No new auth fields in the manifest.
+- **Repositories** — Git repos cloned as working directories (existing)
+- **Skills** — imported skills/commands/agents with type badges and source links
+- **Uploads** — uploaded files (existing)
+
+Users can add skill sources live (Import Skills button). The backend clones the source, writes files to `/workspace/file-uploads/.claude/`, and Claude picks them up immediately. Users can remove individual skills — the file is deleted and Claude stops seeing it.
 
 ### Workflow Metadata
 
-The runner's `/content/workflow-metadata` endpoint returns all discovered skills, commands, and agents across all loaded sources and built-in Claude Code skills. The frontend uses this to populate the Skills toolbar button and `/` autocomplete in the chat input.
+The runner's `/content/workflow-metadata` endpoint returns all discovered skills, commands, and agents from:
+- The active workflow's `.claude/` directory
+- Any additional source directories
+- `/workspace/file-uploads/.claude/` (live imports)
+- Built-in Claude Code skills (batch, simplify, debug, claude-api, loop)
+
+The frontend uses this to populate the Skills toolbar button and `/` autocomplete in the chat input.
 
 ---
 
@@ -251,7 +235,7 @@ claude \
 
 ### 2. Load-workflow skill
 
-A meta-skill that reads a workflow's `ambient.json`, clones each source, and sets them up for Claude:
+A meta-skill that reads a workflow's `ambient.json`, clones each source, and passes them as `--add-dir`:
 
 ```
 ~/.claude/skills/load-workflow/SKILL.md
@@ -265,7 +249,7 @@ Usage:
 The skill instructs Claude to:
 1. Fetch the workflow's `ambient.json`
 2. Clone each source to temp directories
-3. Set up `.claude/` structures so skills are discoverable
+3. Symlink `.claude/` structures into the project
 4. The workflow's `CLAUDE.md` is loaded automatically
 
 This makes ACP workflows portable — anyone with Claude Code can use them without ACP.
@@ -274,4 +258,12 @@ This makes ACP workflows portable — anyone with Claude Code can use them witho
 
 ## Open Questions
 
-1. **"Always add" defaults**: Should some workspace-level sources be auto-loaded into every session? Current proposal: a `default` flag on installed items — pre-selected at session creation, user can uncheck. Needs further discussion.
+1. **Skill versioning**: Sources reference branches today. Should we support tags or SHAs for pinning? What happens when a skill source updates — do sessions get the latest on next start?
+
+2. **Plugin format**: Should workflow export produce a Claude Code plugin (`plugin.json`)? Pros: portable, namespaced, versioned. Cons: plugins cache/copy files which breaks the dynamic reference model.
+
+3. **RHAI alignment**: How does this map to RHAIRFE-1370 (Skills Registry)? Our `sources` format and marketplace could inform the product's in-cluster registry design.
+
+4. **Security**: How do we verify skill sources haven't been tampered with? Git commit SHAs provide content-addressable verification. Enterprise customers may need signed manifests.
+
+5. **Workspace defaults**: Should some workspace-level items be "always-on" (loaded in every session regardless of workflow)? Or should this be handled via org-level Claude Code managed settings?
