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

Reply via email to