From 522efca3d0ceb561018a53752cc378a6a76fb88d Mon Sep 17 00:00:00 2001
From: Joeri Dijkstra <joeri_dijkstra@outlook.com>
Date: Mon, 12 Oct 2026 10:36:53 +0200
Subject: [PATCH] feat: install the agent skill with flux install
 claude|omp|codex

The binary embeds skill/SKILL.md and installs it where each agent reads
personal skills, so brew and go install users get the skill and can
refresh it after upgrading. A changed SKILL.md is backed up first; a
symlinked skill folder or file is refused.
---
 .goreleaser.yml               |   6 ++
 README.md                     |  16 +++
 cmd/install.go                | 131 ++++++++++++++++++++++++
 cmd/install_test.go           | 126 +++++++++++++++++++++++
 docs/specs/install-command.md | 185 ++++++++++++++++++++++++++++++++++
 skill/skill.go                |   8 ++
 6 files changed, 472 insertions(+)
 create mode 100644 cmd/install.go
 create mode 100644 cmd/install_test.go
 create mode 100644 docs/specs/install-command.md
 create mode 100644 skill/skill.go

diff --git a/.goreleaser.yml b/.goreleaser.yml
index 3caddde..a0949a7 100644
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@@ -40,6 +40,12 @@ homebrew_casks:
       git:
         url: git@github.com:eyra/homebrew-tap.git
         private_key: '{{ index .Env "HOMEBREW_TAP_DEPLOY_KEY" }}'
+    caveats: |
+      Install the flux skill for your AI coding agents with one or more of:
+        flux install claude
+        flux install omp
+        flux install codex
+      Rerun them after `brew upgrade flux-cli` to update the skill.
     hooks:
       post:
         install: |
diff --git a/README.md b/README.md
index 07d47a2..dc20287 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,22 @@ Or with Go:
 go install github.com/eyra/flux-cli@latest
 ```
 
+### Agent skill
+
+The binary carries the flux skill for AI coding agents. Install it for the
+agents you use, and rerun after upgrading flux:
+
+```bash
+flux install claude   # Claude Code: ~/.claude/skills/flux (CLAUDE_CONFIG_DIR replaces ~/.claude)
+flux install omp      # omp: ~/.omp/agent/skills/flux (PI_CODING_AGENT_DIR replaces ~/.omp/agent)
+flux install codex    # Codex: ~/.agents/skills/flux
+```
+
+omp also reads `~/.agents/skills`, so `flux install codex` makes the skill
+available to omp too. A `SKILL.md` that differs from the installed version is
+first backed up to `SKILL.md.bak-<time>`. A symlinked skill folder or file is
+left alone, and the command fails.
+
 ## Usage
 
 ### List issues
diff --git a/cmd/install.go b/cmd/install.go
new file mode 100644
index 0000000..3590d57
--- /dev/null
+++ b/cmd/install.go
@@ -0,0 +1,131 @@
+package cmd
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/eyra/flux-cli/skill"
+	"github.com/spf13/cobra"
+)
+
+var installCmd = &cobra.Command{
+	Use:   "install",
+	Short: "Install the flux skill for an AI coding agent",
+	Long: `Install the flux agent skill, embedded in this binary, where an agent reads
+its personal skills:
+
+  claude  ~/.claude/skills/flux      (CLAUDE_CONFIG_DIR replaces ~/.claude)
+  omp     ~/.omp/agent/skills/flux   (PI_CODING_AGENT_DIR replaces ~/.omp/agent)
+  codex   ~/.agents/skills/flux
+
+omp also reads ~/.agents/skills, so "flux install codex" makes the skill
+available to omp too.
+
+Rerun after upgrading flux to update the skill. A SKILL.md that differs from
+this version is first backed up to SKILL.md.bak-<time>.`,
+}
+
+// installTarget returns the command that installs the skill into
+// <root>/skills/flux, where root is $envVar or else ~/defaultRoot.
+func installTarget(name, short, long, envVar, defaultRoot string) *cobra.Command {
+	return &cobra.Command{
+		Use:          name,
+		Short:        short,
+		Long:         long,
+		Args:         cobra.NoArgs,
+		SilenceUsage: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			root := ""
+			if envVar != "" {
+				root = os.Getenv(envVar)
+			}
+			if root == "" {
+				home, err := os.UserHomeDir()
+				if err != nil {
+					return err
+				}
+				root = filepath.Join(home, defaultRoot)
+			}
+			path, backup, err := installSkill(root, skill.Markdown)
+			if err != nil {
+				return err
+			}
+			if jsonFlag {
+				fields := []string{"path", path}
+				if backup != "" {
+					fields = append(fields, "backup", backup)
+				}
+				printOK(fields...)
+				return nil
+			}
+			out := cmd.OutOrStdout()
+			if backup != "" {
+				fmt.Fprintf(out, "Backed up previous skill to %s\n", backup)
+			}
+			fmt.Fprintf(out, "Installed flux skill to %s\n", path)
+			return nil
+		},
+	}
+}
+
+// installSkill writes data to <root>/skills/flux/SKILL.md. An identical file is
+// left alone; a different one is renamed to SKILL.md.bak-<time> first. A
+// symlinked skill folder or file is refused, so a link to a checkout of this
+// repository is never overwritten.
+func installSkill(root string, data []byte) (path, backup string, err error) {
+	dir := filepath.Join(root, "skills", "flux")
+	path = filepath.Join(dir, "SKILL.md")
+	for _, p := range []string{dir, path} {
+		if info, err := os.Lstat(p); err == nil && info.Mode()&fs.ModeSymlink != 0 {
+			target, _ := os.Readlink(p)
+			return "", "", fmt.Errorf("%s is a symlink to %s; remove it to install", p, target)
+		}
+	}
+	existing, err := os.ReadFile(path)
+	switch {
+	case err == nil && bytes.Equal(existing, data):
+		return path, "", nil
+	case err == nil:
+		backup = path + ".bak-" + time.Now().Format("20060102-150405")
+		if err := os.Rename(path, backup); err != nil {
+			return "", "", err
+		}
+	case !errors.Is(err, fs.ErrNotExist):
+		return "", "", err
+	}
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return "", "", err
+	}
+	if err := os.WriteFile(path, data, 0644); err != nil {
+		return "", "", err
+	}
+	return path, backup, nil
+}
+
+func init() {
+	installCmd.AddCommand(
+		installTarget("claude", "Install the flux skill for Claude Code",
+			`Install the flux skill into ~/.claude/skills/flux, where Claude Code reads
+personal skills. CLAUDE_CONFIG_DIR replaces ~/.claude.`,
+			"CLAUDE_CONFIG_DIR", ".claude"),
+		installTarget("omp", "Install the flux skill for omp (oh-my-pi)",
+			`Install the flux skill into ~/.omp/agent/skills/flux, omp's own skills
+folder, which takes priority over every other skill location.
+PI_CODING_AGENT_DIR replaces ~/.omp/agent.
+
+"flux install codex" already makes the skill available to omp, through
+~/.agents/skills; use this command to give omp its own copy.`,
+			"PI_CODING_AGENT_DIR", filepath.Join(".omp", "agent")),
+		installTarget("codex", "Install the flux skill for Codex",
+			`Install the flux skill into ~/.agents/skills/flux, where Codex reads
+personal skills. omp and other agents that read ~/.agents/skills pick it up
+too.`,
+			"", ".agents"),
+	)
+	rootCmd.AddCommand(installCmd)
+}
diff --git a/cmd/install_test.go b/cmd/install_test.go
new file mode 100644
index 0000000..ca79d28
--- /dev/null
+++ b/cmd/install_test.go
@@ -0,0 +1,126 @@
+package cmd
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+)
+
+func TestInstallTargets(t *testing.T) {
+	want, err := os.ReadFile(filepath.Join("..", "skill", "SKILL.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, tc := range []struct {
+		target, envVar, defaultDir string
+	}{
+		{"claude", "CLAUDE_CONFIG_DIR", ".claude"},
+		{"omp", "PI_CODING_AGENT_DIR", ".omp/agent"},
+		{"codex", "", ".agents"},
+	} {
+		for _, override := range []bool{false, true} {
+			if override && tc.envVar == "" {
+				continue
+			}
+			name := tc.target
+			if override {
+				name += " with " + tc.envVar
+			}
+			t.Run(name, func(t *testing.T) {
+				isolateCommand(t)
+				t.Setenv("CLAUDE_CONFIG_DIR", "")
+				t.Setenv("PI_CODING_AGENT_DIR", "")
+				root := filepath.Join(os.Getenv("HOME"), tc.defaultDir)
+				if override {
+					root = t.TempDir()
+					t.Setenv(tc.envVar, root)
+				}
+				command, _, err := installCmd.Find([]string{tc.target})
+				if err != nil {
+					t.Fatal(err)
+				}
+				var output bytes.Buffer
+				out := &cobra.Command{}
+				out.SetOut(&output)
+				if err := command.RunE(out, nil); err != nil {
+					t.Fatal(err)
+				}
+				path := filepath.Join(root, "skills", "flux", "SKILL.md")
+				got, err := os.ReadFile(path)
+				if err != nil || !bytes.Equal(got, want) {
+					t.Fatalf("%s does not hold skill/SKILL.md: %v", path, err)
+				}
+				if output.String() != "Installed flux skill to "+path+"\n" {
+					t.Fatalf("unexpected output: %q", output.String())
+				}
+			})
+		}
+	}
+}
+
+func TestInstallSkillBacksUpLocalEdits(t *testing.T) {
+	root := t.TempDir()
+	path, backup, err := installSkill(root, []byte("v1"))
+	if err != nil || backup != "" {
+		t.Fatalf("fresh install: backup %q, err %v", backup, err)
+	}
+	if _, backup, err = installSkill(root, []byte("v1")); err != nil || backup != "" {
+		t.Fatalf("identical reinstall: backup %q, err %v", backup, err)
+	}
+	if err := os.WriteFile(path, []byte("v1 with local edits"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	if _, backup, err = installSkill(root, []byte("v2")); err != nil || backup == "" {
+		t.Fatalf("changed reinstall: backup %q, err %v", backup, err)
+	}
+	if got, _ := os.ReadFile(backup); string(got) != "v1 with local edits" {
+		t.Fatalf("backup holds %q", got)
+	}
+	if got, _ := os.ReadFile(path); string(got) != "v2" {
+		t.Fatalf("skill holds %q", got)
+	}
+	backups, _ := filepath.Glob(path + ".bak-*")
+	if len(backups) != 1 {
+		t.Fatalf("expected one backup, found %v", backups)
+	}
+}
+
+func TestInstallSkillRefusesSymlinks(t *testing.T) {
+	for _, link := range []string{"folder", "file"} {
+		t.Run(link, func(t *testing.T) {
+			root, checkout := t.TempDir(), t.TempDir()
+			repoSkill := filepath.Join(checkout, "SKILL.md")
+			if err := os.WriteFile(repoSkill, []byte("checkout"), 0644); err != nil {
+				t.Fatal(err)
+			}
+			dir := filepath.Join(root, "skills", "flux")
+			if link == "folder" {
+				if err := os.MkdirAll(filepath.Dir(dir), 0755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.Symlink(checkout, dir); err != nil {
+					t.Fatal(err)
+				}
+			} else {
+				if err := os.MkdirAll(dir, 0755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.Symlink(repoSkill, filepath.Join(dir, "SKILL.md")); err != nil {
+					t.Fatal(err)
+				}
+			}
+			_, _, err := installSkill(root, []byte("release"))
+			if err == nil || !strings.Contains(err.Error(), "is a symlink to") {
+				t.Fatalf("expected a symlink error, got %v", err)
+			}
+			entries, _ := os.ReadDir(checkout)
+			if got, _ := os.ReadFile(repoSkill); string(got) != "checkout" || len(entries) != 1 {
+				t.Fatalf("checkout was touched: %q, %d entries", got, len(entries))
+			}
+		})
+	}
+}
diff --git a/docs/specs/install-command.md b/docs/specs/install-command.md
new file mode 100644
index 0000000..e9ab154
--- /dev/null
+++ b/docs/specs/install-command.md
@@ -0,0 +1,185 @@
+# Spec: `flux install claude` / `omp` / `codex`
+
+- **Status:** implemented (step 1 of "Switching over"). Step 2 waits for the
+  `v0.5.0` release.
+- **Date:** 2026-10-12
+- **Base:** `eyra/flux-cli` `master` at `2aac1bb`; the latest release is `v0.4.0`
+- **Checked against:**
+  - omp 18.8.6: its bundled docs `skills.md`, `settings.md` and `context-files.md`
+  - Claude Code 2.1.281: <https://docs.claude.com/en/docs/claude-code/skills>
+  - Codex: <https://developers.openai.com/codex/skills>, and
+    `openai/codex` `codex-rs/skills/src/parser.rs` at `d24507a`
+  - GoReleaser v2.18 `homebrew_casks` docs, for `caveats`
+  - `eyra/skills` at `db32d79`: `internal/installer/install.go`
+
+## Problem
+
+`brew install eyra/tap/flux-cli` and `go install` only install the binary. The
+agent skill (`skill/SKILL.md`) is only installed by `install.sh`, which copies
+it to `~/.claude/skills/flux`. People who install with brew or Go get no skill,
+and an installed skill goes stale when the binary is upgraded: a skill installed
+in September still documents personas, which #16 removed.
+
+## Commands
+
+```bash
+flux install claude   # Claude Code
+flux install omp      # oh-my-pi (omp)
+flux install codex    # OpenAI Codex
+```
+
+| Command               | Writes                         | Default root   | Root override         |
+| --------------------- | ------------------------------ | -------------- | --------------------- |
+| `flux install claude` | `<root>/skills/flux/SKILL.md`  | `~/.claude`    | `CLAUDE_CONFIG_DIR`   |
+| `flux install omp`    | `<root>/skills/flux/SKILL.md`  | `~/.omp/agent` | `PI_CODING_AGENT_DIR` |
+| `flux install codex`  | `<root>/skills/flux/SKILL.md`  | `~/.agents`    | none                  |
+
+The override variables are the ones Claude Code and omp read themselves, so the
+skill lands where the tool looks. Codex has no override: its user skill
+location is fixed at `$HOME/.agents/skills`
+([Codex docs](https://developers.openai.com/codex/skills)).
+
+### Why omp needs its own target
+
+omp can read `~/.claude/skills`, but only when the user lists `claude` in
+`enabledProviders` (or sets `CLAUDE_CONFIG_DIR`); that is off by default. Without
+it, omp loads user skills only from its native `~/.omp/agent/skills` and from
+`~/.agents/skills`, which Claude Code does not read. So one location does not
+cover both tools.
+
+`flux install omp` uses the native directory: it has omp's highest skill
+priority and does not share `~/.agents/skills`, which the `eyra-skills`
+installer manages. If a user has both copies and has enabled the `claude`
+provider, omp silently drops a byte-identical duplicate. If the copies
+differ, omp keeps the native skill as `flux` and loads the other under a
+namespaced name (`<namespace>/flux`), with a collision warning. Running both
+commands after an upgrade keeps them identical.
+
+### Codex
+
+Codex reads user skills only from `~/.agents/skills` (plus repository
+`.agents/skills` folders and `/etc/codex/skills`), not from `~/.codex`. It
+requires `name` and `description` in the frontmatter, which `SKILL.md` already
+has. Codex picks up new or changed skills without a restart.
+
+`~/.agents/skills` is the folder where the `eyra-skills` installer puts the
+`eyra-*` skills. That installer replaces only its own skill folders, so it
+leaves `flux` alone. omp also reads this folder: with both `omp` and `codex`
+installed, the duplicate rules above apply, and the native omp copy wins.
+
+## Behaviour
+
+- The skill is embedded in the binary (`go:embed`), so the installed skill
+  always matches the binary that installed it. The command does not download
+  anything, and it needs no authentication: it ignores `--env`, `--project` and
+  `--api-key`.
+- It creates missing directories with mode 0755 and writes `SKILL.md` with mode
+  0644.
+- If an existing `SKILL.md` is byte-identical, nothing is written.
+- If an existing `SKILL.md` differs, it is first renamed to
+  `SKILL.md.bak-YYYYMMDD-HHMMSS` beside it (as `install.sh` does now), so local
+  edits are not lost.
+- Output: `Installed flux skill to <path>` (plus `Backed up previous skill to
+  <path>` when a backup was made). With `--json`, `printOK("path", …)`, adding
+  `"backup"` when a backup was made.
+- If `<root>/skills/flux` or its `SKILL.md` is a symlink, nothing is written
+  and the command exits nonzero with
+  `<path> is a symlink to <target>; remove it to install`. Otherwise a
+  developer's link to a `flux-cli/skill` checkout would be overwritten.
+- If a write fails, the command exits nonzero with the OS error.
+- `flux install` without a target shows help listing `claude`, `omp` and
+  `codex`.
+- Both commands stay. The help text says how they overlap, because omp also
+  reads `~/.agents/skills`:
+  - `flux install --help` lists the three targets and their paths, and says
+    that `codex` also makes the skill available to omp.
+  - `flux install omp --help` says it installs into omp's own skills folder,
+    which takes priority, and that `flux install codex` already works for omp.
+  - `flux install codex --help` says it also covers omp and other agents that
+    read `~/.agents/skills`.
+  - The README "Agent skill" subsection repeats this in one sentence.
+
+## Implementation
+
+- `skill/skill.go`: `package skill` with `//go:embed SKILL.md` into
+  `var Markdown []byte`. `go:embed` cannot reach `../skill` from `cmd/`, so
+  the embed lives beside the file.
+- `cmd/install.go`: an `install` parent command. `installTarget` builds the
+  `claude`, `omp` and `codex` subcommands, which resolve their root
+  (environment variable where there is one, else `os.UserHomeDir()` plus the
+  default) and call one `installSkill(root, data)` function.
+- `cmd/install_test.go`:
+  - each target, with and without its override variable, writes exactly
+    `skill/SKILL.md` to the expected path (this also proves the embed)
+  - an identical reinstall makes no backup; a locally edited skill is backed
+    up byte-for-byte, then replaced
+  - a symlinked folder or file is refused, and the link target is left
+    untouched
+
+## Switching over
+
+`install.sh` is served from `master` but downloads the latest *release*
+(`raw.githubusercontent.com/eyra/flux-cli/master/install.sh`). If it calls
+`flux install claude` before a release has that command, every
+`curl … | bash` install fails. CI does not catch this: `install-check.yml`
+tests a locally built archive. So this ships in two steps.
+
+1. First PR, followed by a release (`v0.5.0`). **Done on `feat/install-command`.**
+   - add the command, `skill/skill.go`, the tests and the README "Agent skill"
+     subsection
+   - add cask `caveats` telling users to run `flux install` with `claude`,
+     `omp` and/or `codex`, and to rerun it after `brew upgrade`
+   - leave `install.sh` and the archive `files` unchanged
+2. Second PR, after `v0.5.0` is released:
+   - `install.sh`: replace `install_skill` with `"$INSTALL_DIR/flux" install
+     claude`, and drop `SKILL_DIR` (`CLAUDE_CONFIG_DIR` replaces it)
+   - `.goreleaser.yml`: remove `skill/SKILL.md` from the archive `files`.
+     This must happen in the same PR as the `install.sh` change, because
+     `install.sh` currently reads the skill from the archive.
+   - `scripts/test-install.sh`: drop the "archive contains skill/SKILL.md"
+     check, and keep the install, no-backup and backup checks, now run through
+     `flux install claude`
+
+## Out of scope
+
+- The `eyra-*` workflow skills: `eyra/skills` installs them into
+  `~/.agents/skills` with its own `eyra-skills` installer.
+- omp profiles (`~/.omp/profiles/<name>/agent`): use `PI_CODING_AGENT_DIR`.
+- Project-level installs (`.claude/skills`, `.agents/skills`), uninstalling,
+  and other agents (OpenCode, Gemini and others).
+- Refreshing the skill automatically on upgrade: brew casks should not write to
+  `$HOME`. Add a version check when stale skills cause real trouble.
+
+## Decisions
+
+- Keep both `flux install omp` and `flux install codex`, even though `codex`
+  alone also reaches omp. The help text explains the overlap.
+
+## Findings (2026-10-12)
+
+The open questions from planning are resolved. Each check below ran against
+the binary built from this branch.
+
+1. **Symlinked skill folders.** The proposed rule is implemented and tested.
+2. **Claude Code reads `CLAUDE_CONFIG_DIR/skills`.** Checked with Claude Code
+   2.1.281 without logging in: the `system`/`init` event of
+   `claude -p --output-format stream-json --verbose` lists the skills before
+   any API call. With `CLAUDE_CONFIG_DIR` set to a folder that has the skill,
+   `flux` is listed; with an empty folder it is not, even though
+   `~/.claude/skills/flux` exists. So the override fully replaces `~/.claude`.
+3. **Codex loads the skill.** Checked with `@openai/codex@0.162.1` under a
+   temporary `HOME`, without logging in: `codex app-server` answers the
+   `skills/list` request with `flux`, scope `user`, `enabled: true`, from
+   `~/.agents/skills/flux/SKILL.md`. The multi-line `description` arrives as
+   one line, and `triggers:` is ignored.
+4. **omp loads one copy.** With identical copies in `~/.omp/agent/skills` and
+   `~/.agents/skills`, `omp -p` (18.8.6) lists `flux` once, with no
+   namespaced duplicate.
+5. **The stale skill problem is real.** Running `flux install claude` on the
+   machine this spec was written on backed up the September skill (which still
+   documents personas) to `SKILL.md.bak-20261012-103300` and replaced it.
+6. **`goreleaser check` (v2.18.3) accepts the cask `caveats`.**
+7. **Not fixed here: errors are printed twice.** The whole CLI prints errors
+   as `Error: <msg>` and then `<msg>` again: cobra prints the error, and
+   `Execute` in `cmd/root.go` prints it once more. Fix it separately with
+   `rootCmd.SilenceErrors = true`.
diff --git a/skill/skill.go b/skill/skill.go
new file mode 100644
index 0000000..abf7710
--- /dev/null
+++ b/skill/skill.go
@@ -0,0 +1,8 @@
+// Package skill embeds the flux agent skill, so the binary can install the
+// skill that matches its own commands.
+package skill
+
+import _ "embed"
+
+//go:embed SKILL.md
+var Markdown []byte