Split Claude plugin from agents.md CLI

[josep-reyero]

Summary

This PR looks large in the file diff, but most of the churn is structural: the CLI work adds agents.md support, and the published LFX Skills suite is organized under skills/.

This PR splits LFX Skills into two clear distribution paths:

• Claude Code plugin for Claude Code users.
• agents.md CLI install for Codex, Gemini CLI, OpenCode, and other agents.md-compatible tools.

It also makes the repo helper skills available locally from this repository so contributors can work immediately after cloning, without first installing the runtime suite globally or into another repo.

The README has the detailed install and authoring guidance.

Claude Code Plugin

Once merged, Claude Code users install from the in-repo marketplace:

/plugin marketplace add linuxfoundation/lfx-skills
/plugin install lfx-skills@lfx-skills

The marketplace lives at .claude-plugin/marketplace.json and points to the plugin in this same repo with:

"source": "./"

The plugin is skills-only:

• .claude-plugin/plugin.json exposes the runtime suite with "skills": ["./skills/"].
• Everything under skills/ is part of the published LFX Skills suite.
• The plugin does not install or use the lfx-skills CLI, as not needed.

Versioning is intentionally simple for now:

• .claude-plugin/plugin.json owns the plugin version.
• Claude Code uses that version for cache/update detection.
• If plugin content changes but the version does not change, Claude keeps using the cached plugin.
• Every Claude-facing plugin change should include a SemVer bump in .claude-plugin/plugin.json.

Legacy Claude symlink installs are handled separately. Users who previously installed LFX Skills into Claude Code via symlinks can remove only those old links with:

lfx-skills uninstall --legacy-claude-only

agents.md Support

agents.md-compatible tools use the lfx-skills CLI:

./install.sh

The setup is agent-first: after cloning, users can start their coding agent in this repo and ask it to set up LFX Skills. The README covers the manual fallback too.

The CLI now focuses on agents.md installs only:

• installs runtime skill symlinks from skills/
• installs /lfx-skills-doctor and /lfx-skills-helper from .agents/skills/
• keeps /lfx-install and /lfx-new-skill local to this source repo
• records the install in ~/.lfx-skills/config.json
• records the dev root in ~/.lfx-skills/dev-root
• installs a safe lfx-skills CLI symlink on PATH when possible
• removes agents.md installs and legacy Claude symlinks with explicit uninstall modes

After installation, users update agents.md installs with:

lfx-skills update --pull
lfx-skills doctor

Contributing

New LFX Skills suite skills should be created from this repo with /lfx-new-skill and placed under skills/lfx-<name>/.

For a new suite skill or plugin-visible behavior change, contributors should:

• create or update the skill under skills/
• bump .claude-plugin/plugin.json version when Claude Code users need to receive the change
• validate locally with claude plugin validate .
• commit with DCO and cryptographic signing: git commit -s -S
• avoid co-author trailers

For agents.md installs, contributors can test by running:

./cli/lfx-skills update
./cli/lfx-skills doctor

Dev Root Support

Both distribution paths support the same LFX dev root convention for skills that need to find local LFX repositories.

• agents.md installs set and update ~/.lfx-skills/dev-root through the CLI installer.
• Claude Code plugin skills can read the same ~/.lfx-skills/dev-root file when present.
• If no dev root is configured, dev-root-aware skills fall back to ~/lf and can ask the user whether to set a different path.

Repo-Local Helper Skills

The repo now includes committed helper skills under both:

• .agents/skills/
• .claude/skills/

These make the repo helpers available out of the box when working inside this repository:

• /lfx-install
• /lfx-skills-doctor
• /lfx-skills-helper
• /lfx-new-skill

These helpers are for working on and contributing to this repository locally. They are not part of the published LFX Skills suite.

[andrest50]

The PR looks good. Great job streamlining the installation process skills in not only Claude Code but other agents - it's definitely a big improvement! Please fix the merge conflicts and then I'll re-approve it if needed.

[dealako]

Hey @josep-reyero — thanks for this. It's a big-looking diff, but you called it: most of the churn is the skills/ reorg, and the real new surface is the ~2,400-line bash CLI under cli/lfx-skills + lib/*.sh. I reviewed it with a security pass and a code-quality pass running in parallel alongside my own read, and consolidated everything below.

Overall impression: This is genuinely careful bash. The bash-3.2 discipline is real (no associative arrays, no mapfile, integer-only read -t, the FD-3 stdin trick for doctor --fix), the safety-critical symlink logic consistently refuses to clobber non-symlinks or foreign targets before any rm, and path-with-spaces / jq --arg quoting is right almost everywhere. The security pass found no critical or high-severity issues — every symlink/CLI-symlink removal verifies readlink against an owned source first. The findings below are robustness and polish, plus one process gate.

Security reconciliation

The security audit surfaced only low-severity items, all of which I've folded in: the cmd_list jq string-interpolation (inline above), predictable temp-file names (folded into the config temp-file comment), and the workflow @main pin (acknowledged below). No unresolved critical findings — the approval gate is clear on the security side.

AI / prior-review reconciliation

No CodeRabbit, Cursor, or Copilot comments exist on this PR to reconcile (the earlier Copilot round was on #52 and its two actionable items were already addressed in commit 65fc245). One prior human review: @andrest50 approved on 2026-05-11. I'm not seeing regressions versus that state — my notes are additive.

Issue count

• 🔴 Blocking: 0 code defects. (See the merge-state note below — that is what blocks merge.)
• 🟡 Minor: 5
  • lib/symlinks.sh — failed outcome silently dropped from the install summary
  • cli/lfx-skills — uninstall doesn't validate --scope (--scope=both removes nothing yet prints success)
  • lib/ui.sh — Ctrl-C restores the terminal but doesn't actually cancel the menu
  • lib/config.sh — manifest temp-file leaks on failure under set -e; predictable name
  • cli/lfx-skills — cmd_list splices flag values into the jq program instead of --arg
• ⚪ Nit: 4
  • lib/symlinks.sh:331 — dead : no-op + misleading comment
  • cli/lfx-skills:905 — grep -qx treats the name as a regex (use -qxF)
  • lib/doctor.sh — _emit uses a |-delimited / newline record format; a symlink target path containing | or a newline could shift the --json fields (low-likelihood data-integrity, not a security boundary)
  • .github/workflows/license-header-check.yml:15 — reusable workflow pinned to mutable @main. You've already documented the org-canonical rationale (~22/30 LF repos pin @main, same-org source, pull_request trigger so no fork-secret exposure) in 77998b6 — flagging only for completeness; fine to leave as-is.

Recommendation (not blocking)

There are no automated tests for ~1,500 lines of state-mutating bash (symlink create/remove, manifest JSON I/O, CLI-symlink-on-PATH) — exactly the \u201crefuse to clobber\u201d logic that most benefits from regression coverage. The code is already structured for it (pure probe_*, env-overridable config paths, a text-record doctor pipeline), so a small bats suite over a temp HOME/LFX_SKILLS_CONFIG_DIR sandbox would be high-value as a fast follow-up. I'm not gating the PR on it given the repo has no harness today, but it's the highest-leverage next step.

Merge state

gh reports this PR as CONFLICTING against main. That has to be resolved before merge regardless of the review.

Decision

🔴 Needs changes before approval — driven by the merge conflict, not by any code defect. Please rebase/resolve against main; the 5 minors are worth a quick pass while you're in there. Once conflicts are cleared, none of the remaining items are approval-blockers and I'm happy to re-review and approve. Nice work on this.

[dealako]

[minor] Correctness — failed outcome is silently dropped.

symlinks_create_one can echo failed (lib/symlinks.sh:80-81, 91-92 — e.g. an ln -s error), but this case only handles installed|updated|skipped. A failure still increments n_total (line 146) with no sub-bucket, so the install summary under-counts and the failure never surfaces in the installed/updated/skipped/total line. Add a failed) arm that warns (and ideally a *) catch-all):

      failed)
        n_failed=$((n_failed + 1))
        ;;
      *) ui_warn "  unknown outcome '$outcome' for $skill" ;;

[dealako]

[minor] Correctness — uninstall never validates --scope.

cmd_install validates/desugars scope (both → global,repo, rejects unknown values at cli/lfx-skills:514-521), but cmd_uninstall passes $scope straight through to symlinks_uninstall_all → config_list_symlinks (lib/config.sh:169-178), whose if/elif chain silently matches nothing for any value other than global/repo/empty. So lfx-skills uninstall --scope=both (a natural thing to type, since install accepts it) removes 0 symlinks and still prints “Uninstall complete.” Validate scope here the same way install does, or desugar both.

[dealako]

[minor] Correctness — Ctrl-C does not actually cancel the menu.

The INT/TERM trap restores stty and re-shows the cursor, but after the handler returns bash resumes the read loop, so pressing Ctrl-C mid-selection shows the cursor reappear while the menu keeps running. Split the handler so INT/TERM also exit:

_ui_cb_restore() { [ -n "$_stty_saved" ] && stty "$_stty_saved" 2>/dev/null; printf '\033[?25h' >&2; }
trap '_ui_cb_restore' EXIT
trap '_ui_cb_restore; exit 130' INT TERM

This also fixes the fragile pattern of baking $_stty_saved into the trap string (a single quote in the value would break out of the quoting).

[dealako]

[minor] Robustness — temp file leaks on failure + predictable name.

This (and the same pattern at lines ~104, 125, 156, 207) uses tmp="$cfg.tmp.$$" then jq ... > "$tmp" && mv "$tmp" "$cfg". If jq fails, or mv fails, $tmp is left behind and — because this runs under the caller's set -e — the function aborts without cleanup. This is the single source of truth for the install manifest, so it's worth hardening:

local tmp; tmp="$(mktemp "$cfg.XXXXXX")"
trap 'rm -f "$tmp"' RETURN
jq ... > "$tmp" && mv "$tmp" "$cfg"

mktemp also removes the predictable-name race if LFX_SKILLS_CONFIG_DIR is ever pointed somewhere shared.

[dealako]

[minor] Robustness — cmd_list interpolates flag values into the jq program.

jq_filter is string-built from $scope/$repo (lines 319-324) and spliced into the jq program here, rather than passed via --arg the way cmd_info/config_* correctly do. It's not a real exploit (local user, own flags — jq can't exec a shell), but a value containing " silently breaks the filter. Prefer:

config_read | jq -r --arg scope "$scope" --arg repo "$repo" '
  (.symlinks // [])[]
  | select(($scope == "") or (.scope == $scope))
  | select(($repo == "") or (.repo == $repo))
  | "\(.scope)\t\(.skill)\t\(.link)"' | sort -u

[dealako]

[nit] Dead no-op + misleading comment. The : does nothing; only rm "$target" matters, and the comment says “fall through to ln (will recreate identically)” when the code actually removes-then-recreates. Drop the : and reword the comment.

[dealako]

[nit] grep -qx "$skill" treats the skill name as a regex. Harmless today (names are lfx-[a-z0-9-]+), but a . would match unintendedly. Use grep -qxF "$skill" for a literal compare.

[josep-reyero]

Made obsolete by PR #59