Open
Conversation
…ataconfig, scheduler, user)
…, webauth, fileauth)
…stdoc, elevateword, badword)
…uery, pathmap, duplicatehost, reqheader)
…sctl The .claude/skills/ tree is the install location for third-party skills (see 'gh skill publish' warning). Authored skills belong under skills/ per the agentskills.io specification. The new skills/fessctl/ replaces the prior single-file skill with a SKILL.md + 6 cross-cutting refs + 22 per-feature refs structure (29 files total).
Code-review surfaced systematic issues in the hand-written cross-cutting
reference files (per-feature subagent-generated files were correct):
- json output is the raw Fess admin API response (.response.settings[],
.response.setting, .response.logs[]); rewrite all jq pipelines that
assumed a {success,data} or bare-array shape.
- Resource IDs are positional arguments. No fessctl subcommand accepts
--id; remove every --id flag from examples and document the convention.
- Recipe 1 (initial crawl): webauth has no --name; webauth requires
--web-config-id, so order is webconfig -> webauth, not the reverse.
Fix --included-urls -> --included-url. Use 'scheduler start <ID>'
instead of pointing at --help.
- Recipe 3 (failure investigation): use snake_case API fields
(job_name, job_status, script_result, session_id, etc.).
- Recipe 4 (user provisioning): role/group/user create take name and
password as positional arguments. The user flag is --role/--group
(singular, repeatable), not --roles/--groups.
- Recipe 5 (relevance tuning): boostdoc requires --sort-order;
keymatch/elevateword/relatedquery require --version-no; relatedquery
--queries takes a single newline-joined string, not a JSON array.
- Authentication: drop the invented 'Radmin-api' permission; use the
documented {role}/{group}/{user} permission syntax. Use --permission
(singular), not --permissions.
- conventions.md: add joblog (also read-only), getbyname (user/role/group),
scheduler start/stop to the exceptions list.
- installation.md: 'uv pip install -e src' -> '.' (pyproject is at root).
- features/dataconfig.md: drop the bogus 'fessctl plugin install' tip;
fessctl 0.1.0 does not wrap plugin admin.
The skill is published for general fessctl users, not just contributors working inside a fess-workspace clone. The 'detect FESS_WORKSPACE/repos/fessctl + uv run' branch assumes a layout that does not exist for installed users and pollutes the documentation with workspace-only paths. - SKILL.md detection chain reduced to PATH -> docker (2 branches). - installation.md drops Option B (fess-workspace dev mode) and consolidates PATH installs (pipx / uv tool / source) under Option A. Source install is the right path for anyone working from a local checkout — once installed with 'uv pip install -e .' it shows up on PATH and the chain picks it. - troubleshooting.md generalises the 'slow first invocation' note away from repos/fessctl-specific wording.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
skills/fessctl/so that Claude Code (and any other compatible agent) can drive Fess via thefessctlCLI.SKILL.md(~70 lines) + 6 cross-cutting references (installation / authentication / output-formats / conventions / troubleshooting / workflows) + 22 per-feature references — one per fessctl resource — for a total of 29 files..claude/skills/fessctl/SKILL.md(added in refactor(commands): simplify command modules and add fessctl skill #25)..claude/skills/is the install location for third-party skills; authored skills belong underskills/<name>/per the spec, andgh skill publishwarns about publishing the install tree.Detection chain (documented in SKILL.md)
fessctlon PATH (covers any futurepipx/brew/uv toolinstall)$FESS_WORKSPACE/repos/fessctl+uv run fessctl(dev mode in fess-workspace)docker run --rm ghcr.io/codelibs/fessctl:<tag>(universal fallback)Install (after merge + tag)
```bash
gh skill install codelibs/fessctl fessctl --scope user --agent claude-code
```
Per-feature reference template (every `features/*.md` follows the same 8-section shape)
What it is / When to use / Subcommand surface / Resource JSON shape / Relationships / Gotchas / Examples / See also.
Each per-feature file's subcommand table was generated by reading the actual `@_app.command(...)` decorators in `src/fessctl/commands/.py`. `crawlinginfo` and `joblog` are correctly documented as read-only (list/get/delete only). `scheduler` includes `start`/`stop`. `user`/`role`/`group` include `getbyname`.
Validation performed
Test plan
Out of scope (intentional, follow-ups)
Spec / plan (in fess-workspace, not committed to this repo)