Find the right skill or tool for the task in front of you.
Jev Capability Advisor recommends capabilities from the catalog your agent actually has available. The default general profile compares skills and tools and can attempt up to three complementary recommendations for a compound request. Explicit next_skill mode answers a narrower question: which one skill should the agent consider next? No suitable capability, missing context and provider failures remain distinct outcomes.
Why use it?
- Skills and tools together. Compare an installed workflow with an available MCP or host tool for the task you want to accomplish.
- Choose the scope explicitly. Ask for one next skill when that is all you need; keep the default profile for skills/tools and complete capability coverage. One next skill never means the rest of the task is covered.
- Clear outcomes. Selection, no suitable capability, clarification and provider failures stay distinct. Prematurely stopped compound plans remain incomplete.
- Compact advice, complete selected descriptions. Keep the full diagnostic receipt locally and return only relevant recommendations, conditions and coverage to the host.
- Reuse preparation across tasks. An owner-process interface keeps HTTPS ready and reuses a bounded search index while each task brings a fresh host catalog.
- Inspect the decision boundary. Candidate coverage, requests, timing and provider usage are recorded. Your host controls loading, permissions and execution.
Install and use
Approved scope: optional, requested capability advice and offline inspection are accepted for public catalog promotion. The following installation command applies once the skill is available on the repository's default branch; versioned packages and the plugin-directory update follow the separate release steps below.
npx skills@latest add stark-ai-de/agent-skills --skill jev-capability-advisor -g -a codex
The standalone package uses the portable Agent Skills format and can also be installed with -a cursor or -a claude-code. Earlier Codex qualification covered explicit on-demand invocation of the pre-session candidate, not automatic interception. The new session runtime and other hosts need their own qualification; installation alone is not runtime evidence.
Then ask:
Use $jev-capability-advisor to recommend the available skills or tools for reviewing this pull request and independently inspecting its deployment logs.
Or keep the first check entirely local:
Use $jev-capability-advisor to inspect the candidates for this task without calling TypeSafe.
The helper needs Python 3.10+; it has no third-party Python dependencies, router service or embedding-model download. A fresh Jev recommendation uses your own TypeSafe API key and sends the supplied task plus bounded public capability cards to TypeSafe. Offline inspection needs no key or network. Configure credentials locally; never paste or commit them. The agent needs a current host-supplied catalog: files on disk alone do not establish which tools are available. See the catalog and CLI contract.
This update also prepares the skill for Codex in stark AI Developer 1.6.0. Archive qualification and plugin-directory publication are separate stages; a locally built archive does not mean the directory already carries this update.
One next skill, explicitly
| What you need | Profile | What the answer covers |
|---|---|---|
| Skills and tools for the requested work | general (default) |
One to three recommendations; compound advice remains experimental |
| One eligible skill to load next | next_skill (explicit) |
Exactly one next skill, with remaining work unassessed |
For the narrower workflow, ask:
Use $jev-capability-advisor in next-skill mode: recommend just one skill to load next for this task. Leave the remaining work unassessed.
When the skill's catalog and credentials are already configured, the corresponding command is:
python3 scripts/jev_advisor.py --catalog /path/to/skill-catalog.json \
--query-file /path/to/task.txt --selection-profile next_skill \
--summary --output /path/to/local-receipt.json
Run it from the installed skill directory. Use the existing TYPESAFE_API_KEY, or add --key-file /path/to/local-key; never put the key itself in the command.
- Explicit scope. The user or host chooses this profile. The helper never silently switches the requested scope.
- Skills only. Every enabled catalog entry must be a skill. Disabled tools may remain; enabled tools produce an input error. Keep mixed inventory intact and use
generalfor it. - One choice question. An uncached next-skill recommendation uses at most one provider call. It does not estimate the total number of required capabilities or ask follow-up selection questions.
- Clear remaining work. Success uses
status: next_skillandadditional_work: unassessed. The host checks relevance and restrictions before loading the skill and remains responsible for other deliverables. No-match and clarification remain valid distinct outcomes.
The catalog still has bounded candidate coverage and request sizes. In the September 25 release recheck’s next-skill comparison, this mode used 6.3% less provider input than both measured Hussi variants, with 48/48 skill choices and 16/16 no-match decisions correct. This measures selection input, not total agent tokens or complete-task speed.
Repeated advice and automatic integration
Integrate offers two modes: hook guidance for Codex CLI or Claude Code, and a Python/NDJSON session for a host process you control.
Hook guidance is an explicit opt-in. A short UserPromptSubmit hint asks the agent to consult Jev once for a new actionable task, using general and current. The agent skips follow-ups, explanations and confirmations, honors explicit skill choices, and keeps its permissions and execution ownership. A real advice attempt produces one short status line with the recommendation or fallback reason. The hook itself only emits static context; it neither calls TypeSafe nor stores prompts. There is no background service or host rebuild.
From the installed skill directory, inspect the proposed user-wide Codex registration before applying it:
python3 scripts/jev_hooks.py install --host codex --dry-run
python3 scripts/jev_hooks.py install --host codex
python3 scripts/jev_hooks.py status --host codex
Use --host claude-code for Claude Code. User scope is the default; --scope project --project-root /path/to/project explicitly selects a project. uninstall with the same host/scope removes only the unchanged owned entry. Installation preserves unrelated configuration and keeps ownership records and backups in private user state. Host trust still requires the host's normal review. Linux/WSL, macOS and native Windows are implementation targets; consult the qualification matrix for actual evidence.
Opt-in covers sending a minimal task summary and bounded capability cards to TypeSafe when advice is actually possible. Existing credentials and current, trustworthy host metadata are required. The agent captures a bounded catalog from the running model's skill list and loaded MCP definitions, using verified host defaults and excluding unknown availability or invocation restrictions. Files may enrich already available entries but cannot prove availability; another host session is not an inventory source. Coverage and exclusions stay explicit, and native permissions still govern concrete calls. If no reliable subset, credentials or allowed execution can be established, the agent continues with native selection. The installer does not provision keys or bypass Plan-mode restrictions.
If credentials are stored in an existing local raw-key file, configure its reference explicitly:
python3 scripts/jev_hooks.py install --host codex --key-file /path/to/existing-key
Only the path is stored in private per-host settings, shared by its user/project registrations. Later installs without the option preserve it. A configured file takes precedence over TYPESAFE_API_KEY; an unreadable file causes native fallback, not a silent switch to the environment. The agent reads status for the actual host and passes that local path to the advisor's --key-file. The path and contents never enter provider metadata. Uninstall keeps the credential reference and recorded evidence.
install --advice-consent allow|revoke explicitly records or withdraws the disclosed processing scope per registration. A plain install, ready key and native trust do not imply acceptance. The private catalog evidence checker retains exact current source snapshots and bounded omissions without claiming host attestation.
status separates registration, recorded processing consent, locally observable credential readiness and historical qualification evidence. A readable key file is not an authentication test. Matching file/platform records remain historical while the active host version and session conditions are unverified. Status deliberately does not launch the host to inspect its version; qualify the active host version, integration/registration fingerprints, catalog scope and scenario results separately, and still check current eligibility. The hook reference documents the private evidence format.
For an explicitly adopted repository policy, render a Codex configuration fragment instead:
python3 scripts/jev_hooks.py render --host codex --policy repository-adopted
This command reads no user configuration and writes nothing. The repository policy contract separates adoption, host-owner activation, processing consent, eligible inventory and qualification. Its fixed reminder covers new tasks and material task/capability changes, with unchanged continuations skipped. Missing prerequisites retain native selection and expose the unmet obligation. Apply or remove the reviewed fragment through the host owner's configuration management; the existing installer does not manage it. Consult the qualification evidence; rendering alone does not qualify a host.
The owner-process session instead reuses healthy HTTPS and an unchanged catalog's derived search index across tasks, validates fresh capabilities per request and does not cache decisions. Its profile is fixed at construction. Single general-profile CLI invocations also reuse their connection for compound follow-ups.
Configuration is not automatic-advice qualification. Each host must independently demonstrate hook delivery, eligible inventory and actual adoption under ADR-0057. Bounded same-session catalogs do not claim complete machine inventory or pre-approve every possible tool argument. Installing the ordinary skill/plugin never activates a hook, and selector benchmarks do not prove hook or whole-task performance.
Benchmarks and benefits
Explore the benchmarks for the confirmed next-skill input advantage and the 6.42× Native selection comparison, including sample sizes, measurement windows and limitations. The September 25 measurements match all seven released runtime files. The published Hussi arm had one retained timeout, so no Hussi speed factor is claimed for that run.
The next-skill profile used less selection input than both measured Hussi variants. Our unpublished pooled-HTTPS control remains slightly faster; the complete results disclose it alongside the three public comparison choices.
Product features and measured selection distinguishes source-inspected capabilities from the specific paths timed in the comparison.
Scope
The agent supplies the current catalog and controls loading, permissions and execution. Ordinary skill installation does not intercept prompts; optional hook guidance must be explicitly enabled and independently qualified. General compound advice remains experimental, and omitted candidates can limit either profile. Next-skill advice deliberately leaves additional work unassessed and does not replace a complete plan.
Read the skill instructions for the operational workflow and evaluation record for qualification and known limits.
Release handoff
Promotion accepted on 2026-09-25 for optional, requested advice and offline inspection. The promotion decision records the evidence for all four ADR-0008 criteria. Merge may proceed after current checks pass. Versioned release and plugin-directory publication remain the steps below; automatic host interception remains separately unqualified.
| Component | Prepared version | Distribution |
|---|---|---|
| Jev Capability Advisor | 0.3.0 |
Standalone Agent Skill; optional dist/skills/jev-capability-advisor.zip |
| stark AI Developer | 1.6.0 |
Seven skills in the portable and OpenAI plugin packages; Jev targets CODEX |
| Catalog | Next generated minor after 0.22.0 |
Release Please owns the final version and changelog; no manual root version bump |
The source allowlist, generated portable copy, OpenAI listing and public release handoff issue already include Jev. The skill needs Python 3.10+, a current host-supplied catalog and the user's TypeSafe key for fresh recommendations. Offline inspection needs no key. Installation does not install an automatic prompt hook; Session's connection and index reuse need a retained process.
Maintainer steps
- Merge the approved feature PR after passing checks. Confirm the accepted scope, successful checks on the current head and resolved review threads.
- Review the generated release PR. After the feature merge, let Release Please refresh its draft and confirm the Jev change is included. It owns exactly
package.json,.release-please-manifest.jsonandCHANGELOG.md. If no draft exists, usepnpm run release:manage -- release-pr --confirmfrom protectedmain. Merge the reviewed, passing release PR. - Approve GitHub publication. Inspect the automatically started Publish Release readiness job, then approve its waiting
releaseenvironment deployment. Wait for publication and exact-tag Post-release Evidence to pass. Check the production Pages deployment separately. The release preservesopenai.zip,portable.zipandrelease-subject.jsonas direct assets. - Update the existing OpenAI plugin. Run
pnpm run release:manage -- openai-handoff --tag <ACTUAL_TAG>and upload that release's exactopenai.zip. Follow the seven-skill update checklist. A local ZIP is preparation proof, not the portal upload source. Complete portal review and publication manually. - Verify public installation, then announce. Test the standalone command above and an eligible Codex plugin install/update. Confirm Jev's instructions, scripts and allowed invocation work; verify directory identity and the live benchmark page. Record sanitized lifecycle evidence using the publishing runbook. Publish the launch post only after the distribution it advertises is available.