Runtime cannot find a Skill or Agent

Use this page when Kit installation succeeds but the runtime does not list or recognize an expected Skill or Agent.

Match the runtime session to the install

Confirm all four details from the original install output:

1. Kit name.
2. Target runtime: claude-code or codex.
3. Scope: the current project or --global.
4. Selected Skills, including any --skills or --exclude-skills filter.

A project install is discovered from that project. A global install is discovered from the runtime's user profile. Start a new runtime session after installation so it loads the current inventory, and use that runtime's documented discovery surface.

For example, invoke a Skill named ak:cook with the runtime-specific syntax:

/ak:cook Check this project   # Claude Code
$ak:cook Check this project   # Codex

Agents use a different surface. Claude Code dispatches installed subagents; Codex loads TOML-defined Agents and exposes their agent_<slug> runtime tools. The absence of / or $ invocation syntax does not mean an Agent is missing.

Check the destination that matches the selected delivery:

Check the adapter, not only file presence

ak doctor --adapter claude-code --json
ak doctor --adapter codex --json

Run the command for the target you installed. File presence alone does not prove that runtime registration or configuration is valid. Inspect the report's adapter checks and data.healthy; the default doctor command still exits 0 for an unhealthy report. On Codex, use doctor as an adapter-health signal, not as the only proof of the installed Skill inventory; verify discovery inside the runtime too.

Read codex_install_provenance as a whole-home classification, not a Kit inventory check. ${CODEX_HOME:-~/.codex} is a shared, user-owned root, so this row is healthy when it contains user content and does not require a whole-home AgentKit marker. A legacy marker is not current ownership evidence and its absence is not a reason to initialize, replace, or delete the Codex home. Per-Kit manifests and ownership records govern AgentKit content instead.

For Claude Code installs, use the matching read-only audit described in Kit installation problems. If audit exits 1, resolve the reported drift before debugging runtime discovery.

Read active Claude hook surfaces

The Claude Code hook_registration and hook_log checks inspect every active install surface they can attribute in the current context: user or project scope, and native or plugin delivery. In JSON, registration details list kit, scope, mode, manifest or settings paths, and missing registrations under details.surfaces; hook-log details list each active log under details.logs.

A missing hook log is healthy on a fresh surface and does not prove that the Skill or Agent is missing. A registration warning identifies the affected surface. When Doctor prints one unambiguous repair command, use that exact target, scope, and delivery mode; otherwise repair each named surface explicitly rather than refreshing a different route.

Recover Claude plugin activation

Plugin files are not enough to activate a Claude Code plugin. If the install warns that the claude CLI was not found, run the two complete commands printed in that warning, in order:

claude plugin marketplace add "<marketplace-source>" --scope <project-or-user>
claude plugin install <kit>@<marketplace> --scope <project-or-user>

Use the exact source, plugin reference, and identical scope from the install output. The first command registers the marketplace; the second records the plugin installation in Claude Code. Then close and reopen Claude Code in the intended project. Also start a fresh Claude Code session after switching between native and plugin delivery; an existing session does not reload that mode.

Recover Codex Agent tools

Codex Skills and Agents have separate discovery paths. Skills are native files under .agents/skills and do not require the AgentKit MCP server. Agents are TOML files exposed as agent_<slug> tools by the registered AgentKit runtime.

Inspect codex_mcp_registration in the Codex doctor report. If it says [mcp_servers.ak-agent-runtime] is missing, register it once:

ak doctor --adapter codex --json
ak codex-agent-runtime register
ak codex-agent-runtime serve --list-only

Registration idempotently updates ${CODEX_HOME:-~/.codex}/config.toml and preserves other MCP server entries. The list-only command is read-only and must name the expected Agents before you continue. For project-staged Agents, run the check from the project root with the project as the staging root:

ak codex-agent-runtime serve --list-only --plugin-root .

This override verifies <project>/<kit>/.codex/agents/; it does not move those Agents into user scope or rewrite the registered server. If only the overridden check finds them, resolve the scope mismatch instead of copying TOML files. After registration or scope correction, close and start a fresh Codex session so it reloads MCP configuration.

If Codex cannot find ak:team

This absence is intentional. The Codex adapter excludes the Engineer ak:team Skill because Codex does not provide the complete Agent Teams lifecycle that workflow requires. It does not install a $ak:team invocation or silently substitute ordinary Codex subagents.

The install summary reports Capabilities excluded (unsupported on this target) and names ak-team; JSON uses capabilityExclusions and capabilityExclusionSummaries. A refresh removes an older AgentKit-owned ak-team copy only when its recorded ownership hash still matches. Modified, unowned, or linked copies are preserved, but they are not made supported by remaining on disk. Choose another Codex workflow or use ak:team in a runtime where the Skill is projected and the live team lifecycle is available.

If the install says Hooks were dropped

On a Codex target, a successful install can include this exact summary:

[!] Hooks dropped (unsupported on this target): 1 group - see warnings

This is a supported partial-projection diagnostic, not a hidden install failure. It means the named hook group uses a matcher for Claude tools that has no equivalent in the Codex tool namespace, so that group and its named handlers were not projected. Other compatible hooks and installed Skills or Agents remain separate results; check their lines in the same install summary.

The number counts matcher groups, not files or scripts. JSON install output reports the same limitation in hooksDropped and droppedHookSummaries. The following warning names the affected event, matcher, and handlers.

For Engineer, the PostToolUse group with matcher Agent|Task|TodoWrite|TodoRead invoking session-state.cjs is not projected, so there is no mid-session task-state refresh from that group. Compatible Edit|Write and * groups remain, and task-state refresh still runs at the supported Stop and SubagentStop turn and subagent boundaries. Do not retry with --force, copy Claude hook configuration into Codex, or delete either runtime home to remove the warning.

A Codex hook fails on Windows

An eligible .cjs hook inside the resolved Codex home can run from a path with spaces through an AgentKit-managed sibling .cmd shim. A spaced path outside the Codex home, a path with cmd.exe metacharacters, a non-ASCII shim basename, or unsafe or non-ASCII baked arguments remains unsupported and produces a warning. A path without spaces continues to use the direct command.

Do not move an external hook into the Codex home or hand-edit the generated shim as a workaround. Keep the warning with your redacted diagnostics.

At global scope, AgentKit merges only its owned registrations into the shared ~/.codex/hooks.json, preserves foreign or user structures, and removes empty AgentKit-owned structures when the last owner leaves. Do not hand-edit ownership sidecars or broadly delete the shared hooks file.

Check configuration scope

From the same project directory as the runtime session, run:

ak config prefs resolve
ak config prefs validate

The project file overrides user preferences. A disabled hook preference can change hook behavior, but it does not install a missing Skill or Agent. See Configuration problems before editing a file.

After changing hook state storage or reinstalling hook registrations, restart active Claude Code and Codex sessions before testing. Existing sessions can retain the earlier hook inventory and state paths.

Verify the result

The issue is resolved when the adapter-specific doctor report is healthy, any applicable audit is clean, and a new runtime session in the intended scope lists or recognizes the expected item. If those checks pass but discovery still fails, export a redacted bundle:

ak diagnostics export --json > agentkit-diagnostics.json

Record the Kit, target, scope, selected Skills, and runtime version with the report.

Related pages

• Kit installation problems
• Installing Kits
• Configuration problems