This is an automated email from the ASF dual-hosted git repository.
luigidemasi pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-kit.git
The following commit(s) were added to refs/heads/main by this push:
new ff137f64 fix: document Claude native skill discovery and workspace
upgrades
ff137f64 is described below
commit ff137f644ddcb9329e68859ca234be6ab0663cc2
Author: Matheus André <[email protected]>
AuthorDate: Tue Nov 17 17:28:19 2026 -0300
fix: document Claude native skill discovery and workspace upgrades
Signed-off-by: Matheus André <[email protected]>
---
docs/modules/ROOT/pages/agents.adoc | 45 +++++++++++++++++++++++++---
docs/modules/ROOT/pages/commands.adoc | 3 +-
docs/modules/ROOT/pages/getting-started.adoc | 5 ++--
docs/modules/ROOT/pages/index.adoc | 2 +-
docs/modules/ROOT/pages/ship.adoc | 3 +-
docs/modules/ROOT/pages/skills.adoc | 15 ++++++----
6 files changed, 59 insertions(+), 14 deletions(-)
diff --git a/docs/modules/ROOT/pages/agents.adoc
b/docs/modules/ROOT/pages/agents.adoc
index e245dee6..4fc5f8ce 100644
--- a/docs/modules/ROOT/pages/agents.adoc
+++ b/docs/modules/ROOT/pages/agents.adoc
@@ -31,10 +31,47 @@ reports.
[[claude]]
== Anthropic Claude Code
-`init` writes `CLAUDE.md` (which points to `AGENTS.md`), the slash commands
under `.claude/commands/`, the skills under
-`.claude/skills/`, project settings in `.claude/settings.json` and the MCP
servers in `.mcp.json`. Start with
-`/camel-start`. During `/camel-execute`, independent tasks of the same wave
are dispatched to parallel subagents with
-isolated context windows.
+`init` writes `CLAUDE.md` (which points to `AGENTS.md`), the skills under
`.claude/skills/`, project settings in
+`.claude/settings.json` and the MCP servers in `.mcp.json`. Start with
`/camel-start`. During `/camel-execute`,
+independent tasks of the same wave are dispatched to parallel subagents with
isolated context windows.
+
+[[claude-native-skills]]
+=== Native skill discovery _(development snapshot only)_
+
+Claude Code discovers the skills directly from
`.claude/skills/<skill>/SKILL.md`; `init` no longer generates a
+second set of command files under `.claude/commands/`. The released
{camel-kit-version} still writes those command
+stubs next to the skills.
+
+* The nine public skills (`camel-start`, `camel-brainstorm`, `camel-migrate`,
`camel-plan`, `camel-execute`,
+ `camel-validate`, `camel-ship`, `camel-knowledge` and `camel-debug`) carry
`user-invocable: true` in the generated
+ copy, so each one is available as `+/camel-*+`.
+* Each public skill has a `description` that states when to use it. Claude
Code may use that description to
+ select a skill from the conversation, but the selection is the model's
decision and is not guaranteed; invoke
+ the skill by name when you need a specific stage.
+* The four internal skills (`camel-design`, `camel-implement`, `camel-test`
and `camel-verify`) carry
+ `user-invocable: false` and `disable-model-invocation: true`. They are not
listed as commands and the model does
+ not select them on its own. The pipeline skills still reach their guides by
reading the files.
+
+[[claude-upgrade]]
+=== Upgrading an existing workspace _(development snapshot only)_
+
+Regenerate a workspace created by an earlier Camel Kit from the project root,
then restart Claude Code:
+
+[source,bash]
+----
+camel-kit init --here --ai claude --force
+----
+
+Commit or back up your own edits to generated files first: the `camel-*`
skills are rewritten on every run.
+
+* Regeneration removes only the command files Camel Kit itself used to
generate in `.claude/commands/`: one
+ `<command>.md` for each of the nine public commands. Every other file in
that directory is preserved, including
+ your own commands and custom files whose names start with `camel-`.
+* `init` stops before it writes anything when `.claude`, one of the Claude
directories it manages or the legacy
+ `.claude/commands` path is a symbolic link. The error names the link;
replace it with a real directory and run
+ `init` again.
+* `camel-kit doctor` accepts a configuration that still records
`agent.folder=.claude/commands`, so a workspace
+ that has not been regenerated yet is not reported as broken for that reason.
[[bob2]]
== IBM Bob 2
diff --git a/docs/modules/ROOT/pages/commands.adoc
b/docs/modules/ROOT/pages/commands.adoc
index 279189e5..2609cd8f 100644
--- a/docs/modules/ROOT/pages/commands.adoc
+++ b/docs/modules/ROOT/pages/commands.adoc
@@ -80,7 +80,8 @@ manifests, the registered workspace templates, the exposure
of user-invocable co
permission fields the runtime supports, graph availability, the command
prefix, the prerequisites and common stale
references in generated files. Target specifics: for Codex it parses
`.codex/config.toml`, the exact MCP
allowlists, the prompt approval modes and the required fields of every
custom-agent file; for Bob 2 it fails each
-public skill hidden by `user-invocable: false`; for Qwen it checks
`includeTools` and `trust`; for OpenCode it
+public skill hidden by `user-invocable: false`; for Claude Code it accepts the
legacy
+`agent.folder=.claude/commands` of a workspace that has not been regenerated
yet; for Qwen it checks `includeTools` and `trust`; for OpenCode it
evaluates all configuration layers as one and names the file that defines each
rule. Configurations that predate the
current filter and permission fields produce upgrade warnings; malformed
current ones fail. Internal skills must
exist as skills but must not be exposed as command stubs.
diff --git a/docs/modules/ROOT/pages/getting-started.adoc
b/docs/modules/ROOT/pages/getting-started.adoc
index 7c40772a..0de05451 100644
--- a/docs/modules/ROOT/pages/getting-started.adoc
+++ b/docs/modules/ROOT/pages/getting-started.adoc
@@ -260,8 +260,9 @@ the project. Known limits:
What every target gets::
* `AGENTS.md`, or the agent's equivalent entry file, with the routing table
for the skills.
-* The agent-native skills and entry points, for example `.claude/commands/`
and `.claude/skills/` for Claude Code,
- or `.agents/skills/` for Codex.
+* The agent-native skills and entry points, for example `.claude/skills/` for
Claude Code or
+ `.agents/skills/` for Codex. The released {camel-kit-version} also writes
command stubs to `.claude/commands/`;
+ see xref:agents.adoc#claude-upgrade[upgrading a Claude Code workspace].
* `docs/constitution.md`, the architecture rules every generated route must
follow (see xref:constitution.adoc[]).
* `docs/flows/`, `test/data/` and `schemas/`, empty scaffolds; pipeline
artifacts use the selected runtime's paths.
* `.camel-kit/` with the project configuration, cached catalogs and templates,
and later the pipeline state.
diff --git a/docs/modules/ROOT/pages/index.adoc
b/docs/modules/ROOT/pages/index.adoc
index 319c1a63..88039a8b 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -98,7 +98,7 @@ configuration.
|===
| Agent | Init flag | Primary generated assets | MCP configuration
-| Anthropic Claude Code | `--ai claude` | `CLAUDE.md`, `.claude/commands/`,
`.claude/skills/` | `.mcp.json`
+| Anthropic Claude Code | `--ai claude` | `CLAUDE.md`, `.claude/skills/`,
`.claude/agents/`, `.claude/settings.json` | `.mcp.json`
| IBM Bob 2 (default) | `--ai bob2` | `.bob/custom_modes.yaml`, rules,
`.bob/skills/`, `.bob/agents/`, `.bob/personas/` | `.bob/mcp.json`
| Google Antigravity | `--ai antigravity` | `AGENTS.md`, `.agents/skills/`,
`.agents/agents/`, `.agents/camel-kit-personas/` | `.agents/mcp_config.json`
| OpenAI Codex CLI | `--ai codex` | `AGENTS.md`, `.agents/skills/`,
`.codex/agents/` | `.codex/config.toml`
diff --git a/docs/modules/ROOT/pages/ship.adoc
b/docs/modules/ROOT/pages/ship.adoc
index 39f305e8..b08b443c 100644
--- a/docs/modules/ROOT/pages/ship.adoc
+++ b/docs/modules/ROOT/pages/ship.adoc
@@ -245,7 +245,8 @@ error, including `stale-stage-input` or a permission
denial, and wait for a new
== Entry points per agent
* *Claude Code* and *GitHub Copilot CLI* expose `/camel-ship` through their
skill directories and relay eligible runs
- to their read-only worker; Claude Code's compatibility command stub only
points at the skill.
+ to their read-only worker. Claude Code has no generated command file in the
development snapshot; the
+ compatibility command stub of the released {camel-kit-version} only points
at the skill.
* *IBM Bob 2* exposes the native skill as `$camel-ship` in Bob Shell and
`/camel-ship` in Bob IDE.
* *OpenAI Codex CLI* exposes `$camel-ship` with no generated command file.
* *Google Antigravity* exposes `/camel-ship` through its skills directory and
relays eligible runs to its read-only
diff --git a/docs/modules/ROOT/pages/skills.adoc
b/docs/modules/ROOT/pages/skills.adoc
index 07b1a56a..1258c4c1 100644
--- a/docs/modules/ROOT/pages/skills.adoc
+++ b/docs/modules/ROOT/pages/skills.adoc
@@ -82,11 +82,16 @@ user_invocable: false
In the shared source only `camel-start` sets `user_invocable: true`: it is the
auto-discovered entry point. The
pipeline and utility skills still get entry points, generated per agent:
slash-command stubs where the agent uses
-them, and native project skills on Codex CLI and GitHub Copilot CLI. Generated
copies may add runtime aliases:
-Copilot, Pi and Qwen add a hyphenated `user-invocable` field, Codex rewrites
`+/camel-*+` invocations to `+$camel-*+`
-mentions, and Bob 2 sets both fields to `true` for the nine public skills so
that Bob Shell lists them in `/skills`
-and the `+$camel-*+` picker. Internal skills keep `false` everywhere. The
front matter must match the workflow manifest;
-a test enforces it.
+them, and native project skills on Claude Code _(development snapshot only)_,
Codex CLI and GitHub Copilot CLI.
+Generated copies may add runtime aliases: Copilot, Pi and Qwen add a
hyphenated `user-invocable` field, Codex
+rewrites `+/camel-*+` invocations to `+$camel-*+` mentions. Bob 2 sets both
fields to `true` for the nine public
+skills, so that Bob Shell lists them in `/skills` and the `+$camel-*+` picker.
Claude Code sets
+`user-invocable: true` for all nine public skills and discovers them from
`.claude/skills/` without command stubs.
+Internal skills keep `false` everywhere; on Claude Code,
+Copilot and Pi the four internal skills also get `disable-model-invocation:
true`, which keeps the model from
+selecting them while the pipeline skills still read their guides as files. See
+xref:agents.adoc#claude-native-skills[native skill discovery on Claude Code].
The front matter must match the
+workflow manifest; a test enforces it.
[[progressive]]
== Progressive disclosure