okf-cli-0.11.0.0: help/agents.md

AGENT SKILLS AND ASSIST

okf can install reusable AI-agent "skills" and "subagents" from a shared git
repository (okf-kit) and launch an interactive agent session that uses them.

KIT COMMANDS

  okf kit list                      List skills and subagents available in okf-kit.
  okf kit install NAME              Install one to user scope.
  okf kit install NAME --project    Install into this project (.okf/agents).
  okf kit uninstall NAME            Remove an installed skill or subagent.
  okf kit update [NAME]             Refresh okf-kit and reinstall installed items.
  okf kit status                    Show what is installed and whether it is current.

  list, status, and update accept --json for a versioned JSON document.
  Installation defaults to the manifest's visibility (tool-only if omitted).
  Use --shared to make an item available in every agent session, or --tool-only
  to restrict it to sessions OKF launches. Codex custom agents require shared
  visibility or --accept-shared-codex because Codex cannot isolate them.
  Omit NAME to choose a skill or subagent with fzf. Explicit NAME bypasses
  terminal and fzf probes. The picker requires fzf and a controlling terminal;
  when unavailable it exits 2 before refreshing the repository. Empty kits exit 1.
  Esc/Ctrl-C cancels with exit 0 and no installation (the Kit engine contract;
  bundle/concept pickers instead exit 130). Picker errors exit 1.

ASSIST

  okf agent assist                  Open a contextual interactive session.
  okf agent assist "PROMPT"         Start with an optional task or question.
  okf agent assist --debug          Print live OKF context without launching.
  okf agent assist --print-command  Print the launch command without launching.
  okf agent context [--json]        Inspect the same read-only context snapshot.

  'okf assist' remains an alias with the same flags and agent.assist settings.
  --debug and --print-command are mutually exclusive. Inspection works without
  a terminal or installed provider. Launching requires a controlling terminal.

  Context contains absolute bundle/profile paths, available profile guidance,
  installed OKF kit references and common commands, including which can write.
  Discovery uses depth four, skips hidden/build/symlink directories, and makes
  no network requests. Config values and credentials are omitted. Empty and
  inaccessible optional sources are reported without preventing inspection.
  JSON is one object with schemaVersion 1, workingDirectory, projectRoot,
  bundles, profiles, commands, installedAssets and warnings; it has no clock.

  Project assets use the nearest .git, okf-config.dhall or .okf ancestor, falling
  back to the current directory. Installation and sessions share this policy.

  Both Claude Code and Codex can be launched. The provider you choose is the CLI
  okf runs, so that CLI must be installed: 'claude' for Provider.Claude and
  'codex' for Provider.Codex. A missing binary exits 127 and names the one it
  looked for.

  Flags, each overriding whatever configuration resolved:

    --provider PROVIDER             claude or codex.
    --model MODEL                   Model to pass to the agent.
    --effort LEVEL                  minimal, low, medium, high, xhigh, or max.
    --system-prompt TEXT            Extra system prompt, appended to the agent's
                                    own rather than replacing it.

  The effort levels are the same six for both providers; okf renders whichever
  the chosen CLI actually accepts. Claude Code has no 'minimal' level, so
  '--effort minimal' reaches it as '--effort low', while Codex takes all six
  verbatim as '-c model_reasoning_effort=...'. Use --print-command to see what
  will run.

  Codex sessions enable OKF's tool-only skills through session configuration
  arguments. Ordinary Codex sessions keep those skills disabled. Existing
  installations keep their legacy placement; 'okf kit status' reports requested
  and effective visibility, including visibility-broken when repair is needed.

CONFIGURATION

  Settings live in okf-config.dhall (project) or ~/.config/okf/config.dhall
  (global). Run 'okf config show' to see the effective values and 'okf config
  init' to write a starter file.

  Configurable fields:

    kit.repoUrl
    kit.providers
    agent.provider                  Shared defaults for every command that
    agent.model                     launches an agent.
    agent.effort
    agent.systemPrompt
    agent.assist.provider           Settings for both assist spellings.
    agent.assist.model              These win over the shared defaults above.
    agent.assist.effort
    agent.assist.systemPrompt

  Environment overrides, which beat both files and are deliberately not
  per-command:

    OKF_AGENT_PROVIDER
    OKF_AGENT_MODEL
    OKF_AGENT_EFFORT
    OKF_AGENT_SYSTEM_PROMPT

  Unlike kit.* and profiles.*, agent settings are read from the project file and
  the global file together, so a project can change one field and inherit the
  rest. Run 'okf config agent' to see what each setting resolved to and which
  key or flag supplied it. See 'okf help config' for the full precedence order.

PUBLISHING YOUR OWN SKILL

  1. Add skills/<name>/SKILL.md to the okf-kit repository.
  2. Add a matching entry to its kit.json.
  3. Commit and push.
  4. Run 'okf kit update' to pull it.

  Skills are plain directories with a SKILL.md file. Subagents are Markdown
  persona files under agents/. Both are discovered by the interactive agent after
  installation and an 'okf assist' launch.