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, codex, cursor, dsh, grok, pi, or omp.
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. For Pi, project installs discover portable Skills below .pi/skills/, Agents below .pi/agents/, rules below .pi/rules/, and extensions below .pi/extensions/. Global installs write directly below the active PI_CODING_AGENT_DIR or ~/.pi/agent profile; do not look for an extra .pi/ segment there. Pi has no ak run --target pi route in this release.

For Oh My Pi, distinguish installed discovery from direct dispatch. A project install discovers portable Skills below .omp/skills/ak-<slug>/, with top-level name: ak-<slug> in each projected SKILL.md, plus Agents and rules below .omp/. Body aliases such as /ak:cook and $ak:cook remain unchanged. ak run <kit>/<skill> --target omp resolves and dispatches one Skill separately without changing that selector. Oh My Pi owns its configured backend and credentials, so file presence alone still does not prove that the runtime loaded the content.

For DeepSeek Harness, project installs write Skills below .dsh/skills/ and user installs below ${DSH_HOME:-~/.dsh}/skills/. Setup resolves AGENTKIT_DSH_BIN or dsh and leaves model, authentication, and sandbox ownership with the runtime. ak run <kit>/<skill> --target dsh resolves and dispatches one Skill separately without changing that installed inventory.

Check the destination that matches the selected delivery:

For a global OMP install, resolve the root in the same order as AgentKit: AGENTKIT_OMP_HOME, OMP_HOME, PI_CODING_AGENT_DIR, then ~/.omp/agent. Check skills/<name>/SKILL.md, agents/<name>.md, rules/<name>.md, and the Kit-scoped AGENTKIT-OMP block in AGENTS.md. Unsupported exports under .agentkit/adapters/omp/<kit>/sidecars/ are retained for lifecycle visibility; their presence does not make them active OMP surfaces.

Trusted project OMP also discovers project .agents/skills. If canonical forms such as ak:advise and ak-advise collide, project .omp/skills shadows the project .agents/skills copy for a project OMP install. When a global OMP install is used from that project, project .agents/skills shadows the profile copy. The install warning does not skip OMP emission, delete or rewrite either Skill, alter .agents or OMP settings, require --force, or indicate exit 6.

Check the adapter, not only file presence

ak doctor --json
ak doctor --adapter claude-code --json
ak doctor --adapter codex --json
ak doctor --adapter cursor --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.

This release has no pi_ or omp_-prefixed doctor check group. For Pi, verify the exact project .pi/ paths or active global profile paths above and start a fresh Pi session; do not treat generic doctor output as proof that Pi loaded the projection.

This release has no omp_-prefixed doctor check group. For OMP, run the unfiltered ak doctor --json for shared AgentKit health, inspect data.healthy, then verify the exact project or global paths above and start a fresh OMP session. Do not treat an empty ak doctor --adapter omp result as proof that the OMP projection is healthy.

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-scope Agents, run the check from the project directory, where Codex launches the runtime. No extra flag is needed: the runtime serves the nearest <dir>/.codex/agents/ at or above its working directory. The search stops at the repository root (the first directory with .git), before your home directory, and at the filesystem root.

The runtime serves project Agents only when your Codex config marks that project, or the repository root that contains it, as trusted, the same rule Codex uses to load a project .codex layer. AgentKit does not write that trust. List-only output shows the result on a project agents: line:

• project agents: <dir> means the directory is served. Its Agents are listed with a (project) suffix.
• project agents: skipped (<reason>) means a directory was found but not served. For an untrusted or unrecorded project, the reason explains how to trust it: start Codex in that project and accept the trust prompt, or change that project's trust_level to "trusted" in your Codex config.

A project Agent replaces a user Agent from ~/.codex/agents/ with the same name, and user Agents still win over plugin-staged Kit Agents. A .codex or .codex/agents directory that is a symlink or Windows junction is reported as a link and skipped, and linked TOML files inside the project directory are ignored. If the expected Agents still do not appear, resolve the scope or trust mismatch instead of copying TOML files. After registration, trust, or scope correction, close and start a fresh Codex session so it reloads MCP configuration.

If Codex cannot find ak:team

The Engineer projection includes ak:team as a Codex Skill under <project>/.agents/skills/ak-team/ or ~/.agents/skills/ak-team/. Invoke it as:

$ak:team <template> <context> [flags]

If Codex does not discover it, confirm the Engineer Skill was selected, verify the install path and scope, then start a fresh Codex session. Discovery alone does not prove execution support: the workflow requires live team creation, shared work, messaging, waiting, graceful shutdown, and cleanup. If any required capability is absent or fails, $ak:team must hard-stop and report the observed error rather than silently substitute ordinary Codex subagents.

If the install says Hooks were dropped

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

[!] Hook groups not projected: 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 hooks-root link is refused

A wrapper-managed Codex home may link only its final hooks leaf to the resolved user's canonical ~/.codex/hooks, as a POSIX symlink or a Windows directory junction. AgentKit uses that canonical path for Hook commands, writes, rollback, and ownership. A linked parent, or a leaf that resolves anywhere other than the canonical user hooks directory, is refused.

Inspect the configured CODEX_HOME, the hooks leaf, and its resolved target. Correct the wrapper or filesystem layout; do not use --force, replace a parent with another link, or redirect the leaf to an arbitrary writable directory.

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 sessions for the affected runtime 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

hooksDeferred is a subset of hooksDropped: the harness bridge defers that subscription, which does not mean the runtime cannot express it. Read the summary to distinguish deferred from unsupported groups.