Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/user/cli-reference.md`:
- Around line 1454-1492: The markdown blocks under the "Synopsis", "**Flags:**",
"**Install Locations:**" and "**Examples:**" headings are missing surrounding
blank lines which triggers MD031/MD058; fix by inserting a blank line before and
after the fenced code block under "Synopsis", a blank line before the table
after "**Flags:**", a blank line before the table after "**Install
Locations:**", and a blank line before the fenced code block under
"**Examples:**" (and ensure there is a blank line after each block as well) so
each block is separated from the surrounding headings and text.

In `@pkg/cli/skill_claude_code.go`:
- Around line 230-233: The verify example emits an unsupported flag; update the
fmt.Fprintf call that prints "aicr verify --bundle ./bundles" in
pkg/cli/skill_claude_code.go so the example uses a positional argument instead
(e.g., "aicr verify ./bundles") so the CLI invocation matches the actual parser
and won't cause agents to produce a parse error.

In `@pkg/cli/skill_generator.go`:
- Around line 66-71: The CLI metadata currently omits root/global flags because
cliMeta only has Name, Version, and Commands and extractCLIMeta only walks
root.Commands; add a Flags field (e.g., []flagMeta) to cliMeta and update
extractCLIMeta to also iterate and extract root.Flags (similar to how command
flags are handled in cmdMeta) so global flags like --debug and --log-json are
captured and serialized into the generated skill output; ensure any existing
flag extraction logic (the flagMeta shape and the code used for cmdMeta.Flags)
is reused for the root-level flags.

In `@pkg/cli/skill.go`:
- Around line 47-75: The skill CLI command currently contains business logic;
extract all skill generation and install behavior from skillCmd/runSkillCmd into
a new functional package (e.g., a package that exposes GenerateSkill,
ResolveInstallPath, and InstallSkill/WriteOrStdout functions) and have
runSkillCmd simply validate flags (using skillCmdFlags), call those exported
functions, and format/report results; move handling of generator dispatch,
metadata extraction, overwrite policy, path resolution, and file writes into
those new functions so pkg/cli only captures intent and delegates
implementation.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pkg/cli/skill_claude_code.go`:
- Around line 164-203: The current writeCriteriaValues collects any recipe flag
with completions (recipeMeta.Flags where f.Completions != nil) which incorrectly
includes non-criteria flags like "--format"; update writeCriteriaValues to only
include true recipe criteria flags by adding an explicit filter when building
fields: check a dedicated marker (e.g., f.IsCriteria or f.Metadata["criteria"]
== "true") if available on cmdMeta.Flags, otherwise exclude known
non-criteria/global flags (e.g., skip f.Name == "format" and other global flags
or f.IsGlobal/f.Hidden if present); update the loop that appends to fields
(references: writeCriteriaValues, recipeMeta.Flags, criteriaField, f.Name,
f.Completions) to only append when the flag passes this criteria predicate.

In `@pkg/cli/skill.go`:
- Around line 120-131: The current flow does a pre-check with os.Stat and
confirmOverwrite then separately calls writeSkillFile, creating a TOCTOU race;
instead, move the overwrite decision and the actual file replacement into a
single atomic helper (update or replace writeSkillFile) that: re-checks the
destination with os.Lstat to reject symlinks, writes content to a uniquely named
temp file in the same directory, fsyncs the temp file, then atomically replaces
the target via os.Rename; ensure confirmOverwrite is called before the helper
but have the helper perform the final lstat-and-write+rename so the confirmed
path cannot be swapped between confirmation and write (references:
confirmOverwrite, writeSkillFile, os.Lstat, os.Rename).

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pkg/cli/skill_test.go`:
- Around line 660-683: The test builds a synthetic root instead of exercising
the real CLI root, so change TestSkillCmd_Stdout to use the actual newRootCmd()
(so runSkillCmd() reads cmd.Root() as in production): call root := newRootCmd(),
set root.Writer = &buf (retain capturing output), then run
root.Run(context.Background(),
[]string{"aicr","skill","--agent","claude-code","--stdout"}) and keep the same
assertions; this ensures the test exercises runSkillCmd(), the real top-level
metadata, and stdout formatting rather than the isolated skillCmd().

---

Duplicate comments:
In `@pkg/cli/skill_generator.go`:
- Around line 56-145: The CLI package currently contains domain logic that
should live in a dedicated skill package; move the types and functions
skillGenerator, cliMeta, cmdMeta, flagMeta, flagType* constants,
cmdNameHelp/cmdNameCompletion, isFrameworkCommand, extractCLIMeta,
extractCmdMeta, extractFlagMeta and any generator implementations (e.g.,
claudeCodeGenerator, codexGenerator) plus their installPath/generate methods
into a new package (suggested pkg/skill), change their package declaration, make
any needed identifiers exported (capitalize) for cross-package use, update
imports in the CLI command to call pkg/skill.ExtractCLIMeta (or renamed exports)
and to construct generators from pkg/skill, and run `go vet`/`go test` to fix
compile errors (import paths, visibility) introduced by the move.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pkg/cli/skill.go`:
- Around line 120-129: The os.Stat(path) error is being treated as "missing" for
all failures which can hide real errors; modify the logic around the os.Stat
call used with cmd.Bool("force") and confirmOverwrite so that only
os.ErrNotExist bypasses the overwrite prompt—i.e., if os.Stat(path) returns an
error, check if errors.Is(err, os.ErrNotExist) and only then proceed without
prompting; for any other stat error return that error instead; keep the existing
confirmOverwrite(path, os.Stdin, cmd.Root().Writer) and the early return
behavior when the user declines.

---

Duplicate comments:
In `@pkg/cli/skill_generator.go`:
- Around line 56-348: The code that models skills and performs
generation/installation should be moved out of pkg/cli into a new pkg/skill
package: extract and relocate the skillGenerator interface, cliMeta, cmdMeta,
flagMeta types, constants (flagType*), the functions extractCLIMeta,
extractCmdMeta, extractFlagMeta, userHomeDir, skillInstallPath, writeSkillFile
(and any helper types like completableStringFlag / CompletableFlag used by these
funcs) into pkg/skill; leave CLI-only wiring and user-interaction helpers
(confirmOverwrite, isFrameworkCommand, and any urfave/cli command registration)
in pkg/cli. After moving, update package declarations, imports, and any call
sites to reference pkg/skill (e.g., skill.ExtractCLIMeta, skill.WriteSkillFile
or import alias), and ensure error types (errors.*) and referenced symbols
compile in the new package.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@pkg/cli/skill_claude_code.go`:
- Around line 145-159: The flag Usage text is appended verbatim and may contain
newlines/tabs which break the generated markdown; before inlining use a
normalized/sanitized string (e.g., create a local variable like usage :=
strings.Join(strings.Fields(f.Usage), " ") or strings.ReplaceAll to collapse
newlines/tabs and trim) and use that sanitized variable when building line
(replace uses of f.Usage with usage); apply the same normalization to f.Default
and elements of f.Completions if they might contain whitespace/newlines to
ensure the bullet layout in SKILL.md stays intact.

In `@pkg/cli/skill_generator.go`:
- Around line 74-80: cmdMeta currently lacks a field for positional argument
syntax so generated SKILL.md omits required args; add a field (e.g., ArgsUsage
string) to the cmdMeta struct, populate it in extractCmdMeta by reading
cmd.ArgsUsage, and update writeCommandEntry to include or append that ArgsUsage
(or emit a short synopsis combining Name and ArgsUsage) when rendering each
command so positional arguments like "<bundle-dir>" appear in the output.