Split Claude plugin from agents.md CLI

.agents/skills/lfx-install/SKILL.md

@@ -0,0 +1,183 @@
+---
+# Copyright The Linux Foundation and each contributor to LFX.
+# SPDX-License-Identifier: MIT
+name: lfx-install
+description: >
+  Install or set up LFX Skills for agents.md-compatible tools via the
+  lfx-skills CLI, and point Claude Code-only users to the Claude plugin path.
+  Walks through the choices in plain language: where their LFX repos live,
+  scope, agents config dirs, then runs the installer and verifies. Use
+  whenever the user says "I just cloned this — what now?", "set up lfx skills",
+  "install lfx skills", "I'm new to lfx-skills", or "first-time setup".
+allowed-tools: Bash, Read, Glob, Grep, AskUserQuestion
+---
+
+<!-- Tool names in this file use Claude Code vocabulary. See docs/tool-mapping.md for other platforms. -->
+
+# LFX Skills Install
+
+You guide the user through their first-time install. The bash CLI (`cli/lfx-skills install`) can do this non-interactively if every flag is supplied; this skill is the conversational layer that figures out what those flags should be by asking the user, in plain language, one question at a time.
+
+## Step 1: Verify you're in the clone
+
+This skill only works inside the `lfx-skills` clone. Verify:
+
+```bash
+[ -x ./cli/lfx-skills ] && echo OK || echo NOT_IN_CLONE
+```
+
+If `NOT_IN_CLONE`, tell the user:
+
+> "I only run inside the lfx-skills clone. `cd` to your clone of `linuxfoundation/lfx-skills` and ask again."
+
+Stop.
+
+## Step 2: Probe the system
+
+Run `./cli/lfx-skills` indirectly via its install command's PROBE step — but for the conversation, you also want the data yourself so you can ask informed questions. Do these one-shot probes:
+
+```bash
+# agents.md-compatible CLIs available
+for cli in codex gemini opencode; do
+  command -v "$cli" >/dev/null 2>&1 && echo "$cli"
+done
+
+# Agents config dirs
+ls -d "$HOME"/.agents* 2>/dev/null
+
+# Dev root candidates
+for d in "$HOME/lf" "$HOME/lfx" "$HOME/code/lfx" "$HOME/work/lfx"; do
+  [ -d "$d" ] && echo "$d"
+done
+```
+
+## Step 3: Q1 — Install route
+
+Use `AskUserQuestion`:
+
+> "Which setup do you need? (1) agents.md-compatible tool (Codex, Gemini CLI, OpenCode), (2) Claude Code only, (3) both."
+
+If you detected only one CLI installed, default to it but still confirm.
+
+If the user picks Claude Code only, explain that Claude installs this repo as a plugin and does not use the CLI symlink installer:
+
+```text
+/plugin marketplace add linuxfoundation/lfx-skills
+/plugin install lfx-skills@lfx-skills
+```
+
+If they are testing from a local checkout, tell them to run Claude Code with the local plugin directory or add the local marketplace per the Claude Code plugin docs. Stop after explaining the plugin path; do not run `./cli/lfx-skills install` for Claude-only installs.
+
+If the user picks both, use the plugin path for Claude Code and continue with the CLI flow below for agents.md-compatible tools. The CLI itself remains agents.md-only.
+
+## Step 4: Q2 — Scope
+
+> "Install scope? (1) **Global** — available in every session of your agents.md-compatible tool. (2) **Per-repo** — only in specific repos (their `.agents/skills/`). (3) **Both** — global plus pin into specific repos."
+
+This question goes second so subsequent questions can adapt. (Per-repo only? Skip the global config picker. Global only? Skip the repo picker.)
+
+## Step 5: Q3 — LFX dev root
+
+Show the candidates you probed with their repo counts:
+
+```
+Where do you keep your LFX repo clones?
+  1. ~/lf (12 lf* repos)
+  2. ~/code/lfx (3 lf* repos)
+  3. Custom path…
+```
+
+Use `AskUserQuestion`. If the user already has `LFX_DEV_ROOT` set in the shell, mention it and ask whether to keep it.
+
+If the chosen path doesn't exist, ask whether to create it (`mkdir -p`). If it has zero `lf*` git repos, warn but proceed: the install will still work; the dev-root-empty doctor warning will trigger until they clone some.
+
+## Step 6: Q4 — Agents config dirs (only if scope includes Global)
+
+If you saw multiple `~/.agents*` config dirs, ask which to install into:
+
+> "I see these agents config dirs: …. Install into all of them, or just one? (defaults to `~/.agents`)"
+
+Most users have one; this only matters for power users with multiple profiles.
+
+If scope is Per-repo only, skip this step entirely.
+
+## Step 7: Q5 — Repos (only if scope includes Per-repo)
+
+List `lf*` git repos under the chosen dev root:
+
+> "Which repos? Pick numbers (e.g., `1, 3, 5`), `all`, or `none`."
+
+If scope is Global only, skip this step entirely.
+
+## Step 8: Show the plan
+
+Before running anything, summarise:
+
+```
+Plan:
+  Scope:          global + per-repo
+  LFX_DEV_ROOT:   ~/lf
+  Agents dir:     ~/.agents
+  Repos (4):      lfx-v2-ui, lfx-v2-meeting-service, lfx-v2-committee-service, lfx-v2-query-service
+  Skills:         runtime suite + lfx-skills-doctor + lfx-skills-helper
+
+Will create approximately N symlinks. Proceed?
+```
+
+`AskUserQuestion`. If no, stop.
+
+## Step 9: Run the installer
+
+Compose the non-interactive flags from the user's answers:
+
+```bash
+./cli/lfx-skills install --yes \
+  --scope=<scope> \
+  --lfx-dev-root=<path> \
+  --agents-config=<dir> \
+  --repos=<repo1,repo2,...>
+```
+
+Stream the output to the user.
+
+## Step 10: Verify
+
+Run a quick verification:
+
+```bash
+./cli/lfx-skills doctor
+```
+
+If errors, walk the user through the auto-fix:
+
+> "One or more checks failed. Want me to run `/lfx-skills-doctor` to investigate?"
+
+## Step 11: Confirm the CLI is on PATH
+
+The installer creates a symlink at a writable PATH dir (`~/.local/bin/lfx-skills`, `~/bin/lfx-skills`, or `/usr/local/bin/lfx-skills`) so the user can type `lfx-skills` from anywhere — no shell rc edit. Read the install output to see which path was used and tell the user:
+
+> "`lfx-skills` is now at `<reported path>` and ready to use from any terminal."
+
+If the installer reported it couldn't find a writable PATH dir, share the alias snippet it printed:
+
+> "I couldn't find a writable PATH dir to drop the CLI into. Add this alias to your shell rc to use `lfx-skills` from anywhere:
+> ```bash
+> alias lfx-skills='<clone>/cli/lfx-skills'
+> ```
+> Or extend PATH to include `~/.local/bin`, `~/bin`, or `/usr/local/bin`."
+
+## Step 12: Suggest next steps
+
+> "All set. Next:
+>
+> 1. Restart your AI coding assistant (or open a new session).
+> 2. `cd` to any LFX repo and type `/lfx` — that's your plain-language entry point.
+> 3. Run `/lfx-skills-doctor` anytime to recheck the install.
+> 4. Run `/lfx-skills-helper` to manage what's installed where."
+
+## What this skill does NOT do
+
+- **Edit your shell rc** — never. Always print the snippet for the user to paste.
+- **Install only some skills** — v1 always installs everything (the full set per chosen target). Filtering is a v2 idea.
+- **Run outside the clone** — bail in Step 1.
+- **Re-run silently** — confirm at the plan step before doing anything stateful.

.agents/skills/lfx-new-skill/SKILL.md

@@ -0,0 +1,138 @@
+---
+# Copyright The Linux Foundation and each contributor to LFX.
+# SPDX-License-Identifier: MIT
+name: lfx-new-skill
+description: >
+  Scaffold a new LFX Skills suite skill under skills/. Use when someone wants
+  to add a new lfx skill, provides a complete SKILL.md to import, has an idea
+  for a skill and wants help drafting it, or asks how to create a skill.
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion
+---
+
+<!-- Tool names in this file use Claude Code vocabulary. See docs/tool-mapping.md for other platforms. -->
+
+# LFX New Skill — Scaffolder
+
+You help contributors add LFX Skills suite skills under `skills/lfx-<name>/`. Read [`references/conventions-quickref.md`](references/conventions-quickref.md) before writing files.
+
+Use two modes:
+
+- **Complete skill provided:** if the user pastes or points to a complete `SKILL.md`, use it as the source of truth. Preserve the body. Only normalize frontmatter, license header, directory name, and repo-specific placeholders when needed.
+- **Draft from idea:** if the user only has an idea, help write the body. Ask targeted questions about trigger phrases, inputs, steps, tools, outputs, and boundaries. Draft concrete step-by-step instructions from the answers.
+
+## Step 1: Verify Location
+
+Run:
+
+```bash
+[ -x ./cli/lfx-skills ] && [ -d ./skills/lfx ] && echo OK || echo NOT_IN_CLONE
+```
+
+If `NOT_IN_CLONE`, tell the user to `cd` to the `lfx-skills` clone and stop.
+
+## Step 2: Gather Inputs
+
+Ask whether the user has a complete `SKILL.md` or wants help drafting one.
+
+For a complete skill:
+
+- Read the supplied file/content.
+- Extract `name`, `description`, and `allowed-tools` when present.
+- Ask only for missing required fields.
+
+For a draft:
+
+- Ask for the skill name. It must match `^lfx-[a-z0-9-]+$` and not already exist under `skills/`.
+- Ask for a frontmatter description with 3-5 trigger phrases.
+- Ask which tools it needs. Default: `Bash, Read, Glob, Grep, AskUserQuestion`.
+- Ask what the skill should do, what inputs it needs, what it may inspect or modify, what output it should produce, and what it must not do.
+
+Ask whether it needs `references/`.
+
+## Step 3: Write Files
+
+Create:
+
+```text
+skills/lfx-<name>/SKILL.md
+```
+
+If requested, also create:
+
+```text
+skills/lfx-<name>/references/.gitkeep
+```
+
+Ensure:
+
+- frontmatter starts on line 1
+- license comments are lines 2-3 inside the frontmatter
+- `name:` equals the directory basename
+- `description:` uses a YAML folded scalar
+- `allowed-tools:` is present
+- MCP-dependent skills include a `## Prerequisites` section
+
+If the skill is user-facing, ask whether to add routing guidance to `skills/lfx/SKILL.md`. Internal-only skills can remain unrouted.
+
+## Step 4: Validate
+
+Run only the new skill formatting check:
+
+```bash
+./cli/lfx-skills doctor --skill-formatting-only --skill=lfx-<name>
+```
+
+Fix `frontmatter-*` and `license-missing` issues, then rerun until clean. Do not run the full doctor for this scaffolding check; full doctor includes agents.md install/setup checks.
+
+## Step 5: Explain Local Testing
+
+Ask which runtime they want to test: Claude Code plugin, agents.md, or both.
+
+For Claude Code plugin testing:
+
+- Give the user this validation command to run from their normal terminal:
+
+  ```bash
+  cd "<absolute-path-to-lfx-skills>"
+  claude plugin validate .
+  ```
+
+- Ask which target LFX repo they want to test in. Resolve a repo name under `~/.lfx-skills/dev-root` or use the absolute path they provide.
+- Give the user a ready-to-run command:
+
+  ```bash
+  LFX_SKILLS_CLONE="<absolute-path-to-lfx-skills>"
+  cd "<resolved-target-repo-path>"
+  claude --plugin-dir "$LFX_SKILLS_CLONE"
+  ```
+
+- Tell them to run `/lfx-skills:lfx-<name>` in that Claude Code session.
+
+For agents.md testing:
+
+- Run `./cli/lfx-skills update`.
+- Tell the user to restart their agents.md-compatible coding agent and run `/lfx-<name>`.
+- If LFX Skills is not installed for agents.md, point them to `/lfx-install` or `./install.sh`.
+
+Keep the two paths separate: the CLI is for agents.md installs; Claude Code uses the plugin path.
+
+## Step 6: Offer Commit And Release Help
+
+After validation, ask whether the user wants help committing the scaffolded skill.
+
+If they say yes:
+
+- Review `git diff` and `git status`.
+- Commit only the intended files.
+- Use `git commit -s -S`.
+- Do not add co-author trailers.
+- Do not push unless explicitly asked.
+
+For plugin versioning, explain that Claude Code picks up plugin changes when `.claude-plugin/plugin.json` gets a new SemVer `version` and the change reaches `main`. Offer to help choose the next patch/minor/major version and include the plugin version bump in the signed commit when plugin-visible behavior changed.
+
+## Boundaries
+
+- Do not install or repair the user's LFX Skills setup; route that to `/lfx-install` or `/lfx-skills-doctor`.
+- Do not use the CLI to install Claude Code skills.
+- Do not run Claude Code plugin commands for agents.md testing.
+- Do not invent unclear behavior. Ask when scope, inputs, outputs, or safety boundaries are unclear.