From eb3ad46273b0a9b2efad5d8ed12728fb81b854b3 Mon Sep 17 00:00:00 2001 From: Ambient Code Bot Date: Tue, 31 Mar 2026 11:48:27 -0500 Subject: [PATCH 1/6] =?UTF-8?q?spec:=20skills=20and=20workflows=20?= =?UTF-8?q?=E2=80=94=20discovery,=20installation,=20and=20usage?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Define the architecture for how skills, workflows, and agents work in ACP: - Workflow = prompt + list of skill source references (not embedded copies) - Skills are the atomic reusable unit, discovered by Claude Code from add_dirs - Manifest format (workflow.yaml) is the core contract — consumed by ACP runner, local load-workflow skill, or Claude Code plugin - Three pillars: discovery (marketplace), installation (workspace library with per-session selection), usage (layered loading into add_dirs) - Local portability: same manifest works with manual --add-dir, a meta-skill, or a Claude Code SessionStart hook plugin --- specs/skills-and-workflows.md | 333 ++++++++++++++++++++++++++++++++++ 1 file changed, 333 insertions(+) create mode 100644 specs/skills-and-workflows.md diff --git a/specs/skills-and-workflows.md b/specs/skills-and-workflows.md new file mode 100644 index 000000000..f7b5dc66f --- /dev/null +++ b/specs/skills-and-workflows.md @@ -0,0 +1,333 @@ +# Skills & Workflows: Discovery, Installation, and Usage + +## Summary + +A workflow is a prompt plus a list of skill sources. Skills are the atomic reusable unit. ACP automates the cloning and wiring; locally, the same manifest format works with a simple skill or script. The manifest format is the contract — ACP and local tooling are just consumers. + +--- + +## Core Concepts + +### Skill + +The atomic unit of reusable capability. A directory containing a `SKILL.md` file with YAML frontmatter and markdown instructions. Claude Code discovers skills from `.claude/skills/{name}/SKILL.md` in the working directory, parent directories, `--add-dir` directories, and plugins. + +Skills have live change detection in `--add-dir` directories — place a new skill file and Claude discovers it immediately without restarting. Skills are invoked via `/skill-name` or auto-triggered by Claude based on the description in frontmatter. + +Commands (`.claude/commands/{name}.md`) and agents (`.claude/agents/{name}.md`) follow the same discovery pattern and are treated as peers to skills throughout this spec. "Skill" is used as shorthand for all three unless distinction matters. + +### Workflow + +A workflow is two things: + +1. **A prompt** — the directive, methodology, persona instructions. What today lives in `CLAUDE.md` + `.ambient/ambient.json` (system prompt, startup prompt, phase descriptions). +2. **A list of skill sources** — references to skills, commands, and agents from various Git repos or registries. Not embedded copies — references resolved at load time. + +A workflow does not contain skills. It references them. The bug-fix workflow becomes: + +```yaml +name: Bug Fix +description: Systematic bug resolution with phased approach +prompt: | + You are a systematic bug fixer. Follow these phases: + 1. Use /assess to understand the issue + 2. Use /reproduce to create a failing test + 3. Use /diagnose to find the root cause + 4. Use /fix to implement the minimal fix + 5. Use /test to verify the fix + 6. Use /review to self-review before PR +sources: + - url: https://github.com/ambient-code/skills.git + path: bugfix/assess + - url: https://github.com/ambient-code/skills.git + path: bugfix/reproduce + - url: https://github.com/ambient-code/skills.git + path: bugfix/diagnose + - url: https://github.com/ambient-code/skills.git + path: bugfix/fix + - url: https://github.com/ambient-code/skills.git + path: bugfix/test + - url: https://github.com/ambient-code/skills.git + path: bugfix/review + - url: https://github.com/opendatahub-io/ai-helpers.git + path: helpers/skills/jira-activity +``` + +Skills are the reusable atoms. Workflows are recipes. The same skill can appear in multiple workflows. + +### Agent (future) + +A persona — prose defining what an agent is responsible for. "Backend Agent", "Security Agent", "PM Agent". An Agent uses workflows and standalone skills to accomplish its goals. An Agent is a session template with a personality: + +``` +Agent = Persona (prompt/directive) + Workflows (skill bundles) + Standalone skills +``` + +A "Bug Fix Agent" = bug-fix persona + bug-fix workflow skills + any additional skills. Same skills reusable by different Agents with different motivations. + +### Manifest Format + +The workflow manifest (`workflow.yaml` or `ambient.json`) is the core deliverable. It defines prompt + skill sources. Multiple consumers read the same format: + +- **ACP runner**: clones sources, adds to `add_dirs`, injects prompt +- **Local script/skill**: clones sources to temp dirs, passes as `--add-dir` +- **Claude Code plugin**: `SessionStart` hook reads manifest, sets up environment + +The format must support: +- Prompt text (inline or file reference) +- Skill sources (Git URL + branch + path) +- Optional: system prompt, startup prompt, rubric +- Optional: environment variables, MCP server configs + +--- + +## Discovery + +### What + +A way to browse and find skills, workflows, and plugins from curated sources. + +### How + +A cluster-level ConfigMap (`marketplace-sources`) holds available registry sources. Each source is one of: + +- A Git repo with a `data.json` catalog (like ai-helpers at `https://opendatahub-io.github.io/ai-helpers/data.json`) +- A Claude Code `marketplace.json` (native plugin marketplace format) +- A direct Git repo with skills/commands/agents in `.claude/` or at root level + +The Marketplace page in the ACP UI shows: + +- Browsable catalogs from each source with search and type filters (skill / command / agent / workflow) +- Compact card tiles with name, description, type badge +- Detail panel on click with full description, source repo link, allowed tools +- "Import Custom" to scan any Git URL and discover items +- Direct one-click install to workspace + +### Scanning + +When given a Git URL (from marketplace or custom), the backend: + +1. Shallow clones the repo +2. Applies optional path filter (subdirectory) +3. Scans for items in both patterns: + - `.claude/skills/*/SKILL.md`, `.claude/commands/*.md`, `.claude/agents/*.md` + - `skills/*/SKILL.md`, `commands/*.md`, `agents/*.md` (registry layout like ai-helpers) +4. Checks for `.ambient/ambient.json` (indicates this is a workflow) +5. Checks for `CLAUDE.md` (indicates project instructions) +6. Returns discovered items with frontmatter metadata + +### Alignment with Claude Code + +Adopting Claude Code's `marketplace.json` format where possible makes ACP skills portable. Users could add the same marketplace from local Claude Code via `/plugin marketplace add`. The catalog format should normalize to the same shape regardless of source type. + +--- + +## Installation & Configuration + +### Workspace Level + +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. + +When creating a session, users select which installed items to include. The workflow they choose may also pull in its own skill dependencies from the manifest. + +### Session Level + +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, 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 + +### Workflow Builder + +A UI for composing workflows from standalone skills: + +- Select skills from the workspace library or browse marketplace +- Each skill is a reference (source URL + path), not a copy +- Define the workflow prompt (methodology, phases, instructions) +- Optionally configure: system prompt, startup prompt, rubric +- Save as a workflow manifest that can be: + - Stored in the workspace + - Exported as a Git repo + - Exported as a Claude Code plugin (`plugin.json`) + +The key constraint: skills are never copied into the workflow. The manifest holds references. At load time, the runner resolves dependencies and clones each source. + +### How Selection Works + +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 manifest declares its skill dependencies — those are auto-loaded +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 skills to the workspace doesn't bloat every session +- The workflow controls its own dependencies +- Users can augment with extras per session +- Workspace-level "always-on" skills could be supported via a flag but are not the default + +--- + +## Usage in Sessions + +### Loading + +When a session starts, sources are loaded in layers: + +1. **Workflow sources** — skills referenced in the workflow manifest, 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 + +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. + +The `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` env var is set so that `CLAUDE.md` files from add-dirs are also loaded (workflow instructions, skill documentation). + +### Runtime Management + +The session context panel shows: + +- **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 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. + +--- + +## Local Usage (outside ACP) + +The same workflow manifest works locally. Two approaches: + +### 1. Manual (no tooling) + +```bash +git clone --depth 1 https://github.com/ambient-code/skills.git /tmp/skills +git clone --depth 1 https://github.com/opendatahub-io/ai-helpers.git /tmp/ai-helpers + +claude \ + --add-dir /tmp/skills/bugfix \ + --add-dir /tmp/ai-helpers/helpers +``` + +### 2. Load-workflow skill + +A meta-skill that reads a workflow manifest and sets up the environment: + +``` +~/.claude/skills/load-workflow/SKILL.md +``` + +Usage: +``` +/load-workflow https://github.com/ambient-code/workflows/tree/main/workflows/bugfix +``` + +The skill instructs Claude to: +1. Fetch the workflow manifest +2. Clone each skill source to temp directories +3. Symlink `.claude/skills/` structures into the project +4. Apply the workflow prompt + +This makes ACP workflows portable — anyone with Claude Code can use them without ACP. The skill ships as part of ai-helpers or as its own standalone skill. + +### 3. Claude Code plugin (future) + +A plugin with a `SessionStart` hook that reads workflow manifests: + +```json +{ + "name": "ambient-workflows", + "hooks": { + "SessionStart": [{ + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/load-workflow.sh" + }] + } +} +``` + +The hook script reads a `workflow.yaml` from the project root (if present), clones skill sources, and symlinks them into place. Fully automated, no user action needed. + +--- + +## Manifest Format (proposed) + +```yaml +# workflow.yaml or ambient.json +name: Bug Fix +description: Systematic bug resolution with phased approach + +# The prompt/instructions — can be inline or reference a file +prompt: | + You are a systematic bug fixer... + +# Optional: injected as system prompt (short, persona-level) +systemPrompt: You are an expert software engineer focused on fixing bugs systematically. + +# Optional: sent as first message when session starts +startupPrompt: | + Welcome! I'm ready to help you fix a bug. + Use /assess to get started, or describe the issue directly. + +# Skill sources — cloned and added to add_dirs +sources: + - url: https://github.com/ambient-code/skills.git + branch: main + path: bugfix/assess + - url: https://github.com/ambient-code/skills.git + path: bugfix/reproduce + - url: https://github.com/opendatahub-io/ai-helpers.git + path: helpers/skills/jira-activity + - url: https://github.com/my-org/internal-skills.git + branch: v2 + path: code-review + +# Optional: quality evaluation criteria +rubric: + activationPrompt: After completing the fix, evaluate your work + criteria: + - name: Root cause identified + weight: 0.3 + - name: Minimal change + weight: 0.2 + - name: Tests added + weight: 0.3 + - name: No regressions + weight: 0.2 +``` + +This format is consumed by: +- ACP runner (production) +- `/load-workflow` skill (local) +- Claude Code plugin hook (automated local) +- Workflow builder UI (creation/editing) + +--- + +## Open Questions + +1. **Manifest format**: YAML vs JSON? Should we extend `ambient.json` or create a new `workflow.yaml`? The existing `ambient.json` has `name`, `description`, `systemPrompt`, `startupPrompt`, `rubric` — we'd add `sources` and `prompt`. + +2. **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? + +3. **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. + +4. **RHAI alignment**: How does this map to RHAIRFE-1370 (Skills Registry)? Our manifest format and marketplace could inform the product's in-cluster registry design. + +5. **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. + +6. **Workspace defaults**: Should some workspace-level items be "always-on" (loaded in every session regardless of workflow)? Example: company-wide coding standards skill. Or should this be handled via org-level Claude Code managed settings? From 3624813ad82c75385befa54bd2cd4e4324de904c Mon Sep 17 00:00:00 2001 From: Ambient Code Bot Date: Tue, 31 Mar 2026 15:18:35 -0500 Subject: [PATCH 2/6] =?UTF-8?q?spec:=20apply=20review=20feedback=20?= =?UTF-8?q?=E2=80=94=20consolidate=20prompts,=20add=20sources=20to=20ambie?= =?UTF-8?q?nt.json?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolved all reviewer comments: - Drop systemPrompt/startupPrompt from ambient.json, prompt lives in CLAUDE.md only - Remove workflow.yaml concept, sources go in ambient.json - Remove manifest-as-contract/multiple-consumers framing - Sources support both structured {url, branch, path} and single URL string - Scanner expects three source types: Claude Code plugins, marketplace catalogs, and standalone .claude repos - Keep rubric as-is (optional, existing workflows use it) - Auth for private sources uses existing workspace credential system - Multi-agent orchestration noted as out of scope - Local usage simplified to manual --add-dir or /load-workflow skill --- specs/skills-and-workflows.md | 246 +++++++++++++--------------------- 1 file changed, 91 insertions(+), 155 deletions(-) diff --git a/specs/skills-and-workflows.md b/specs/skills-and-workflows.md index f7b5dc66f..cf08523c9 100644 --- a/specs/skills-and-workflows.md +++ b/specs/skills-and-workflows.md @@ -2,7 +2,7 @@ ## Summary -A workflow is a prompt plus a list of skill sources. Skills are the atomic reusable unit. ACP automates the cloning and wiring; locally, the same manifest format works with a simple skill or script. The manifest format is the contract — ACP and local tooling are just consumers. +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. --- @@ -20,39 +20,53 @@ Commands (`.claude/commands/{name}.md`) and agents (`.claude/agents/{name}.md`) A workflow is two things: -1. **A prompt** — the directive, methodology, persona instructions. What today lives in `CLAUDE.md` + `.ambient/ambient.json` (system prompt, startup prompt, phase descriptions). -2. **A list of skill sources** — references to skills, commands, and agents from various Git repos or registries. Not embedded copies — references resolved at load time. +1. **A prompt** — the directive and methodology, written as `CLAUDE.md` in the workflow directory. This is the only prompt mechanism — no separate `systemPrompt` or `startupPrompt` fields. +2. **A list of sources** — references in `ambient.json` to skills, commands, agents, and plugins from various Git repos. Not embedded copies — references resolved at load time. A workflow does not contain skills. It references them. The bug-fix workflow becomes: -```yaml -name: Bug Fix -description: Systematic bug resolution with phased approach -prompt: | - You are a systematic bug fixer. Follow these phases: - 1. Use /assess to understand the issue - 2. Use /reproduce to create a failing test - 3. Use /diagnose to find the root cause - 4. Use /fix to implement the minimal fix - 5. Use /test to verify the fix - 6. Use /review to self-review before PR -sources: - - url: https://github.com/ambient-code/skills.git - path: bugfix/assess - - url: https://github.com/ambient-code/skills.git - path: bugfix/reproduce - - url: https://github.com/ambient-code/skills.git - path: bugfix/diagnose - - url: https://github.com/ambient-code/skills.git - path: bugfix/fix - - url: https://github.com/ambient-code/skills.git - path: bugfix/test - - url: https://github.com/ambient-code/skills.git - path: bugfix/review - - url: https://github.com/opendatahub-io/ai-helpers.git - path: helpers/skills/jira-activity +**`CLAUDE.md`**: +```markdown +You are a systematic bug fixer. Follow these phases: +1. Use /assess to understand the issue +2. Use /reproduce to create a failing test +3. Use /diagnose to find the root cause +4. Use /fix to implement the minimal fix +5. Use /test to verify the fix +6. Use /review to self-review before PR ``` +**`ambient.json`**: +```json +{ + "name": "Bug Fix", + "description": "Systematic bug resolution with phased approach", + "sources": [ + {"url": "https://github.com/ambient-code/skills.git", "branch": "main", "path": "bugfix/assess"}, + {"url": "https://github.com/ambient-code/skills.git", "path": "bugfix/reproduce"}, + {"url": "https://github.com/ambient-code/skills.git", "path": "bugfix/diagnose"}, + {"url": "https://github.com/ambient-code/skills.git", "path": "bugfix/fix"}, + {"url": "https://github.com/ambient-code/skills.git", "path": "bugfix/test"}, + {"url": "https://github.com/ambient-code/skills.git", "path": "bugfix/review"}, + {"url": "https://github.com/opendatahub-io/ai-helpers.git", "path": "helpers/skills/jira-activity"}, + "https://github.com/my-org/shared-skills/tree/main/code-review" + ], + "rubric": { + "activationPrompt": "After completing the fix, evaluate your work", + "criteria": [ + {"name": "Root cause identified", "weight": 0.3}, + {"name": "Tests added", "weight": 0.3}, + {"name": "Minimal change", "weight": 0.2}, + {"name": "No regressions", "weight": 0.2} + ] + } +} +``` + +Sources support two formats: +- **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. ### Agent (future) @@ -60,24 +74,12 @@ Skills are the reusable atoms. Workflows are recipes. The same skill can appear A persona — prose defining what an agent is responsible for. "Backend Agent", "Security Agent", "PM Agent". An Agent uses workflows and standalone skills to accomplish its goals. An Agent is a session template with a personality: ``` -Agent = Persona (prompt/directive) + Workflows (skill bundles) + Standalone skills +Agent = Persona (CLAUDE.md) + Workflows (skill bundles) + Standalone skills ``` A "Bug Fix Agent" = bug-fix persona + bug-fix workflow skills + any additional skills. Same skills reusable by different Agents with different motivations. -### Manifest Format - -The workflow manifest (`workflow.yaml` or `ambient.json`) is the core deliverable. It defines prompt + skill sources. Multiple consumers read the same format: - -- **ACP runner**: clones sources, adds to `add_dirs`, injects prompt -- **Local script/skill**: clones sources to temp dirs, passes as `--add-dir` -- **Claude Code plugin**: `SessionStart` hook reads manifest, sets up environment - -The format must support: -- Prompt text (inline or file reference) -- Skill sources (Git URL + branch + path) -- Optional: system prompt, startup prompt, rubric -- Optional: environment variables, MCP server configs +Multi-agent orchestration (research agent → writer agent → editor agent pipelines) is a separate design problem out of scope for this spec. --- @@ -87,19 +89,23 @@ The format must support: A way to browse and find skills, workflows, and plugins from curated sources. -### How +### Source Types + +The scanner must support three types of sources: + +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`. -A cluster-level ConfigMap (`marketplace-sources`) holds available registry sources. Each source is one of: +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`. -- A Git repo with a `data.json` catalog (like ai-helpers at `https://opendatahub-io.github.io/ai-helpers/data.json`) -- A Claude Code `marketplace.json` (native plugin marketplace format) -- A direct Git repo with skills/commands/agents in `.claude/` or at root level +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). -The Marketplace page in the ACP UI shows: +### 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 (skill / command / agent / workflow) +- Browsable catalogs from each source with search and type filters - Compact card tiles with name, description, type badge -- Detail panel on click with full description, source repo link, allowed tools +- 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 @@ -109,16 +115,17 @@ When given a Git URL (from marketplace or custom), the backend: 1. Shallow clones the repo 2. Applies optional path filter (subdirectory) -3. Scans for items in both patterns: +3. Checks for `.claude-plugin/plugin.json` (Claude Code plugin format) +4. Scans for items in both patterns: - `.claude/skills/*/SKILL.md`, `.claude/commands/*.md`, `.claude/agents/*.md` - - `skills/*/SKILL.md`, `commands/*.md`, `agents/*.md` (registry layout like ai-helpers) -4. Checks for `.ambient/ambient.json` (indicates this is a workflow) -5. Checks for `CLAUDE.md` (indicates project instructions) -6. Returns discovered items with frontmatter metadata + - `skills/*/SKILL.md`, `commands/*.md`, `agents/*.md` (registry layout) +5. Checks for `.ambient/ambient.json` (indicates this is a workflow) +6. Checks for `CLAUDE.md` (indicates project instructions) +7. Returns discovered items with frontmatter metadata -### Alignment with Claude Code +### Format Alignment -Adopting Claude Code's `marketplace.json` format where possible makes ACP skills portable. Users could add the same marketplace from local Claude Code via `/plugin marketplace add`. The catalog format should normalize to the same shape regardless of source type. +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. --- @@ -128,7 +135,7 @@ Adopting Claude Code's `marketplace.json` format where possible makes ACP skills 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. -When creating a session, users select which installed items to include. The workflow they choose may also pull in its own skill dependencies from the manifest. +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 @@ -146,21 +153,22 @@ A UI for composing workflows from standalone skills: - Select skills from the workspace library or browse marketplace - Each skill is a reference (source URL + path), not a copy -- Define the workflow prompt (methodology, phases, instructions) -- Optionally configure: system prompt, startup prompt, rubric -- Save as a workflow manifest that can be: +- 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 (`plugin.json`) + - Exported as a Claude Code plugin -The key constraint: skills are never copied into the workflow. The manifest holds references. At load time, the runner resolves dependencies and clones each source. +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 library is not auto-injected. Selection happens at session creation: 1. User picks a workflow (or "General chat" for none) -2. The workflow manifest declares its skill dependencies — those are auto-loaded +2. The workflow's `ambient.json` `sources` array declares dependencies — those are auto-loaded 3. User can optionally add standalone skills from the workspace library 4. The session CRD stores the workflow reference + any additional skill sources @@ -178,13 +186,17 @@ This means: When a session starts, sources are loaded in layers: -1. **Workflow sources** — skills referenced in the workflow manifest, cloned and added to `add_dirs` +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 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. -The `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` env var is set so that `CLAUDE.md` files from add-dirs are also loaded (workflow instructions, skill documentation). +The `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` env var is set so that `CLAUDE.md` files from add-dirs are also loaded. + +### Authentication for Sources + +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. ### Runtime Management @@ -210,9 +222,7 @@ The frontend uses this to populate the Skills toolbar button and `/` autocomplet ## Local Usage (outside ACP) -The same workflow manifest works locally. Two approaches: - -### 1. Manual (no tooling) +### 1. Manual ```bash git clone --depth 1 https://github.com/ambient-code/skills.git /tmp/skills @@ -225,7 +235,7 @@ claude \ ### 2. Load-workflow skill -A meta-skill that reads a workflow manifest and sets up the environment: +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 @@ -237,97 +247,23 @@ Usage: ``` The skill instructs Claude to: -1. Fetch the workflow manifest -2. Clone each skill source to temp directories -3. Symlink `.claude/skills/` structures into the project -4. Apply the workflow prompt - -This makes ACP workflows portable — anyone with Claude Code can use them without ACP. The skill ships as part of ai-helpers or as its own standalone skill. - -### 3. Claude Code plugin (future) - -A plugin with a `SessionStart` hook that reads workflow manifests: - -```json -{ - "name": "ambient-workflows", - "hooks": { - "SessionStart": [{ - "type": "command", - "command": "${CLAUDE_PLUGIN_ROOT}/scripts/load-workflow.sh" - }] - } -} -``` - -The hook script reads a `workflow.yaml` from the project root (if present), clones skill sources, and symlinks them into place. Fully automated, no user action needed. - ---- - -## Manifest Format (proposed) - -```yaml -# workflow.yaml or ambient.json -name: Bug Fix -description: Systematic bug resolution with phased approach - -# The prompt/instructions — can be inline or reference a file -prompt: | - You are a systematic bug fixer... - -# Optional: injected as system prompt (short, persona-level) -systemPrompt: You are an expert software engineer focused on fixing bugs systematically. - -# Optional: sent as first message when session starts -startupPrompt: | - Welcome! I'm ready to help you fix a bug. - Use /assess to get started, or describe the issue directly. - -# Skill sources — cloned and added to add_dirs -sources: - - url: https://github.com/ambient-code/skills.git - branch: main - path: bugfix/assess - - url: https://github.com/ambient-code/skills.git - path: bugfix/reproduce - - url: https://github.com/opendatahub-io/ai-helpers.git - path: helpers/skills/jira-activity - - url: https://github.com/my-org/internal-skills.git - branch: v2 - path: code-review - -# Optional: quality evaluation criteria -rubric: - activationPrompt: After completing the fix, evaluate your work - criteria: - - name: Root cause identified - weight: 0.3 - - name: Minimal change - weight: 0.2 - - name: Tests added - weight: 0.3 - - name: No regressions - weight: 0.2 -``` +1. Fetch the workflow's `ambient.json` +2. Clone each source to temp directories +3. Symlink `.claude/` structures into the project +4. The workflow's `CLAUDE.md` is loaded automatically -This format is consumed by: -- ACP runner (production) -- `/load-workflow` skill (local) -- Claude Code plugin hook (automated local) -- Workflow builder UI (creation/editing) +This makes ACP workflows portable — anyone with Claude Code can use them without ACP. --- ## Open Questions -1. **Manifest format**: YAML vs JSON? Should we extend `ambient.json` or create a new `workflow.yaml`? The existing `ambient.json` has `name`, `description`, `systemPrompt`, `startupPrompt`, `rubric` — we'd add `sources` and `prompt`. - -2. **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? +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? -3. **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. +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. -4. **RHAI alignment**: How does this map to RHAIRFE-1370 (Skills Registry)? Our manifest format and marketplace could inform the product's in-cluster registry design. +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. -5. **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. +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. -6. **Workspace defaults**: Should some workspace-level items be "always-on" (loaded in every session regardless of workflow)? Example: company-wide coding standards skill. Or should this be handled via org-level Claude Code managed settings? +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? From 7b79e2b25ca46e98ef0e48268ff8e6d9e4c8bad5 Mon Sep 17 00:00:00 2001 From: Ambient Code Bot Date: Tue, 31 Mar 2026 15:46:24 -0500 Subject: [PATCH 3/6] spec: apply all review feedback (48 comments resolved) Major changes: - Everything is a source reference, no type distinction - Marketplace behind feature flag - Workflow builder removed (not MVP), replaced with visualization - Skills go where Claude expects (not file-uploads), exact path TBD - Versioning: branch (auto-update) + optional sha/tag (pinning) - Selection: registry = available, session picks, 'always add' TBD - Removed from scope: plugin export, RHAI alignment, security/supply chain - All examples in JSON (not YAML), ambient.json only - Local usage simplified to manual --add-dir or /load-workflow skill --- specs/skills-and-workflows.md | 108 ++++++++++++++++------------------ 1 file changed, 50 insertions(+), 58 deletions(-) diff --git a/specs/skills-and-workflows.md b/specs/skills-and-workflows.md index cf08523c9..b3517f620 100644 --- 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. ACP automates the cloning and wiring. Locally, a `/load-workflow` skill or manual `--add-dir` does the same thing. +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. --- @@ -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 +- **Structured object**: `{"url": "...", "branch": "...", "path": "..."}` — works with any Git host, branch is explicit. Supports optional `tag` or `sha` field for pinning. - **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,6 +85,8 @@ 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. @@ -97,7 +99,7 @@ The scanner must support three types of sources: 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`. -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). +3. **Standalone repos with `.claude/`** — any Git repo containing `.claude/skills/`, `.claude/commands/`, `.claude/agents/`. Also supports root-level `skills/`, `commands/`, `agents/` (registry layout). ### How @@ -105,7 +107,7 @@ A cluster-level ConfigMap (`marketplace-sources`) holds available registry sourc - Browsable catalogs from each source with search and type filters - Compact card tiles with name, description, type badge -- Detail panel on click with full description, source repo link +- Detail panel on click showing extracted skills, commands, and agents inside the source — rendered readably, not as a raw file viewer - "Import Custom" to scan any Git URL and discover items - Direct one-click install to workspace @@ -125,58 +127,64 @@ 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. Our catalog format normalizes to the same shape regardless of source type. +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. --- ## Installation & Configuration +### Everything is a Source Reference + +All installed items are source references — Git URLs pointing to repos containing skills, plugins, or workflows. There is no type distinction in the data model. The runner auto-detects what each source contains when it clones and scans. + ### Workspace Level -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. +Source references installed at the workspace level are stored in the ProjectSettings CR. These represent the workspace's **registry** — what's available to sessions. -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`. +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 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.) ### Session Level -Skills can be added to a running session via the context panel: +Sources 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, writes skill files to `/workspace/file-uploads/.claude/` -- Claude discovers them via live change detection (already in `add_dirs`) +- Backend clones, scans, loads skills into discoverable locations +- Claude discovers them via live change detection - Persisted via S3 state-sync on session suspend/resume -### Workflow Builder +### Skill Storage in the Runner + +Skills, commands, and agents must end up where Claude Code expects them for automatic discovery. The workspace root already has a `.claude/` directory that is persisted by state-sync. Sources should be loaded so their contents are discoverable — either via `add_dirs` pointing to each source's `.claude/` structure, or by writing directly into the workspace `.claude/`. The exact mechanism needs further discussion, but the key constraint is: Claude must discover them without any non-standard configuration. -A UI for composing workflows from standalone skills: +Plugins and workflows should also be co-located in this space for consistency. -- 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 +### Versioning + +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: + +```json +{"url": "https://github.com/org/skills.git", "branch": "main", "path": "assess", "sha": "a1b2c3d4"} +``` -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. +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. ### How Selection Works -The workspace library is not auto-injected. Selection happens at session creation: +The workspace registry 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 optionally add standalone skills from the workspace library -4. The session CRD stores the workflow reference + any additional skill sources +3. User can add any number of additional sources from the workspace registry — workflows, skills, commands, plugins, anything +4. The session stores the workflow reference + any additional source references This means: -- Installing 50 skills to the workspace doesn't bloat every session +- Installing 50 sources to the workspace doesn't bloat every session - The workflow controls its own dependencies - Users can augment with extras per session -- Workspace-level "always-on" skills could be supported via a flag but are not the default +- "Always add" items provide workspace-level defaults (needs further design) --- @@ -186,37 +194,27 @@ This means: When a session starts, sources are loaded in layers: -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 +1. **Workflow sources** — skills from the workflow's `ambient.json` `sources` array, cloned and loaded +2. **Additional sources** — extra sources the user selected at session creation +3. **Live additions** — sources imported during the session via the context panel -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. +All layers make skills discoverable by Claude Code through the standard `.claude/skills/`, `.claude/commands/`, `.claude/agents/` directory structure. -The `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` env var is set so that `CLAUDE.md` files from add-dirs are also loaded. +### Visualization -### Authentication for Sources - -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. +Users should be able to see what's loaded in a session — not as raw files, but as extracted, readable metadata: -### Runtime Management +**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. -The session context panel shows: +**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. -- **Repositories** — Git repos cloned as working directories (existing) -- **Skills** — imported skills/commands/agents with type badges and source links -- **Uploads** — uploaded files (existing) +### Authentication for Sources -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. +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. ### Workflow Metadata -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. +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. --- @@ -235,7 +233,7 @@ claude \ ### 2. Load-workflow skill -A meta-skill that reads a workflow's `ambient.json`, clones each source, and passes them as `--add-dir`: +A meta-skill that reads a workflow's `ambient.json`, clones each source, and sets them up for Claude: ``` ~/.claude/skills/load-workflow/SKILL.md @@ -249,7 +247,7 @@ Usage: The skill instructs Claude to: 1. Fetch the workflow's `ambient.json` 2. Clone each source to temp directories -3. Symlink `.claude/` structures into the project +3. Set up `.claude/` structures so skills are discoverable 4. The workflow's `CLAUDE.md` is loaded automatically This makes ACP workflows portable — anyone with Claude Code can use them without ACP. @@ -258,12 +256,6 @@ This makes ACP workflows portable — anyone with Claude Code can use them witho ## Open Questions -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. +1. **Skill storage path**: Should sources be loaded into the workspace root `.claude/` (simple, persisted) or as separate `add_dirs` per source (clean separation)? Need to investigate `add_dirs` limits and understand the tradeoffs. -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? +2. **"Always add" defaults**: Should some workspace-level sources be auto-loaded into every session? How is this configured? Needs further discussion. From 348d978d61b5d63e4e88d5d109b15f62184380a3 Mon Sep 17 00:00:00 2001 From: Ambient Code Bot Date: Tue, 31 Mar 2026 15:53:52 -0500 Subject: [PATCH 4/6] =?UTF-8?q?spec:=20resolve=20skill=20storage=20?= =?UTF-8?q?=E2=80=94=20separate=20add=5Fdirs=20per=20source?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each source gets /workspace/sources/{name}/ as its own add_dir. Claude Code discovers .claude/skills/ inside each automatically. Clean separation, no conflicts, simple removal, standard mechanism. Mirrors how repos work (/workspace/repos/{name}/). Removed skill storage path from open questions (resolved). --- specs/skills-and-workflows.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/specs/skills-and-workflows.md b/specs/skills-and-workflows.md index b3517f620..bd22aa1fb 100644 --- a/specs/skills-and-workflows.md +++ b/specs/skills-and-workflows.md @@ -157,9 +157,21 @@ Sources can be added to a running session via the context panel: ### Skill Storage in the Runner -Skills, commands, and agents must end up where Claude Code expects them for automatic discovery. The workspace root already has a `.claude/` directory that is persisted by state-sync. Sources should be loaded so their contents are discoverable — either via `add_dirs` pointing to each source's `.claude/` structure, or by writing directly into the workspace `.claude/`. The exact mechanism needs further discussion, but the key constraint is: Claude must discover them without any non-standard configuration. +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. -Plugins and workflows should also be co-located in this space for consistency. +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. ### Versioning @@ -194,11 +206,11 @@ This means: When a session starts, sources are loaded in layers: -1. **Workflow sources** — skills from the workflow's `ambient.json` `sources` array, cloned and loaded -2. **Additional sources** — extra sources the user selected at session creation -3. **Live additions** — sources imported during the session via the context panel +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 -All layers make skills discoverable by Claude Code through the standard `.claude/skills/`, `.claude/commands/`, `.claude/agents/` directory structure. +Each source directory contains `.claude/skills/`, `.claude/commands/`, `.claude/agents/` as appropriate. Claude Code discovers from all `add_dirs` automatically. ### Visualization @@ -256,6 +268,4 @@ This makes ACP workflows portable — anyone with Claude Code can use them witho ## Open Questions -1. **Skill storage path**: Should sources be loaded into the workspace root `.claude/` (simple, persisted) or as separate `add_dirs` per source (clean separation)? Need to investigate `add_dirs` limits and understand the tradeoffs. - -2. **"Always add" defaults**: Should some workspace-level sources be auto-loaded into every session? How is this configured? Needs further discussion. +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. From 47271fe83fdf9a5f5fb8291d9a4d66619dc45efa Mon Sep 17 00:00:00 2001 From: Ambient Code Bot Date: Tue, 31 Mar 2026 15:56:46 -0500 Subject: [PATCH 5/6] spec: clarify plugins are discovery-only, not runtime MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plugins (plugin.json, marketplace.json) are read by the marketplace for browsing and display. At runtime, everything is a source reference — cloned to /workspace/sources/{name}/ and added to add_dirs. No plugin hooks, MCP, or LSP at session runtime. --- specs/skills-and-workflows.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/specs/skills-and-workflows.md b/specs/skills-and-workflows.md index bd22aa1fb..99571defc 100644 --- a/specs/skills-and-workflows.md +++ b/specs/skills-and-workflows.md @@ -91,16 +91,22 @@ Discovery is behind a feature flag. A way to browse and find skills, workflows, and plugins from curated sources. -### Source Types +### Discovery vs Runtime -The scanner must support three types of sources: +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. -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`. +### Source Types (for discovery/browsing) -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`. +The marketplace scanner must read these formats to display available items: + +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. + +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. 3. **Standalone repos with `.claude/`** — any Git repo containing `.claude/skills/`, `.claude/commands/`, `.claude/agents/`. Also supports root-level `skills/`, `commands/`, `agents/` (registry layout). +4. **Catalog JSON** — `data.json` files (like ai-helpers) listing items with metadata. Normalized to the same display format. + ### How A cluster-level ConfigMap (`marketplace-sources`) holds available registry sources. The Marketplace page in the ACP UI shows: @@ -135,7 +141,7 @@ We follow Claude Code's plugin and skill formats as the standard. The [Agent Ski ### Everything is a Source Reference -All installed items are source references — Git URLs pointing to repos containing skills, plugins, or workflows. There is no type distinction in the data model. The runner auto-detects what each source contains when it clones and scans. +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 @@ -189,7 +195,7 @@ The workspace registry is not auto-injected. Selection happens at session creati 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 — workflows, skills, commands, plugins, anything +3. User can add any number of additional sources from the workspace registry 4. The session stores the workflow reference + any additional source references This means: From f00769cd79dd255404c418db6835257fe696c99e Mon Sep 17 00:00:00 2001 From: Gage Krumbach Date: Tue, 31 Mar 2026 15:29:28 -0500 Subject: [PATCH 6/6] =?UTF-8?q?spec:=20skills=20and=20workflows=20?= =?UTF-8?q?=E2=80=94=20discovery,=20installation,=20and=20usage=20(#1117)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 & 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 --- specs/skills-and-workflows.md | 134 ++++++++++++++++------------------ 1 file changed, 63 insertions(+), 71 deletions(-) diff --git a/specs/skills-and-workflows.md b/specs/skills-and-workflows.md index 99571defc..cf08523c9 100644 --- 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,27 +85,19 @@ 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 @@ -113,7 +105,7 @@ A cluster-level ConfigMap (`marketplace-sources`) holds available registry sourc - 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?