> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextmoca.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent skills

> Drop-in Needlepath integration skills for Claude Code and Codex, so a coding agent can wire Needlepath into your application without you learning the wire contract first.

An **integration skill** is a folder of instructions you drop into your own
repository. Ours is `needlepath-integration`. Your coding agent reads it, inspects your application, and writes
the integration for you: the right SDK or adapter, shadow-first rollout,
fail-open handling, metrics, configuration and boundary tests.

You then review a diff, the way you would review any other change.

## What it is not

This distinction matters, because all four of these are ways to put Needlepath
in front of a model call and only one of them is what this page is about.

|                                     | Runs where                             | What it does                                                                                                                                 |
| ----------------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration skill** *(this page)* | Your coding agent, at development time | Writes the integration into your codebase. Ships nothing into production itself.                                                             |
| **SDK**                             | In your process, at run time           | `pip install needlepath` or `npm install @nextmoca/needlepath-sdk`. The thing the skill usually wires up. See [Integrations](/integrations). |
| **MCP server**                      | Alongside your agent, at run time      | Exposes tools to an agent over the Model Context Protocol. Needlepath does not ship one today.                                               |
| **Model proxy or interceptor**      | In the request path, at run time       | Sits between your app and a provider. The LiteLLM guardrail path is this shape.                                                              |

The skill is a **build-time author**, not a run-time component. Once it has run,
your repository depends on an SDK or on the HTTP API, and not on the skill.

## Install for Claude Code

<CodeGroup>
  ```bash Plugin marketplace theme={null}
  /plugin marketplace add nextmoca/needlepath-skills
  /plugin install needlepath-integration@needlepath
  ```

  ```bash Cross-agent installer theme={null}
  npx skills add nextmoca/needlepath-skills
  ```

  ```bash Manual theme={null}
  git clone https://github.com/nextmoca/needlepath-skills
  mkdir -p .claude/skills
  cp -r needlepath-skills/skills/needlepath-integration .claude/skills/
  ```
</CodeGroup>

The marketplace route gives you version pinning and `/plugin marketplace update`.
The manual route is a plain copy, which is the one to use when your policy is
that nothing self-updates.

## Install for Codex

Codex loads skills from `.agents/skills/`, in this order:

| Scope             | Path                        |
| ----------------- | --------------------------- |
| Repository        | `$CWD/.agents/skills`       |
| Repository parent | `$CWD/../.agents/skills`    |
| Repository root   | `$REPO_ROOT/.agents/skills` |
| User              | `$HOME/.agents/skills`      |
| Admin             | `/etc/codex/skills`         |

<Warning>
  It is `.agents/skills`, **not** `.codex/skills`. Several third-party guides say
  `.codex/skills`; a skill placed there is never loaded, and the failure is silent
  because Codex simply does not see it.
</Warning>

<CodeGroup>
  ```bash Cross-agent installer theme={null}
  npx skills add nextmoca/needlepath-skills
  ```

  ```bash Manual theme={null}
  git clone https://github.com/nextmoca/needlepath-skills
  mkdir -p .agents/skills
  cp -r needlepath-skills/skills/needlepath-integration .agents/skills/
  ```
</CodeGroup>

## Your first integration

With the skill installed, ask for the integration in your own words. Naming the
operating point is worth doing explicitly:

```text theme={null}
Integrate Needlepath (operating point np-2026-08-r4) into this application with shadow rollout,
fail-open behavior, metrics, and tests.
```

That wording is the skill's own default prompt, shipped in its Codex metadata,
so it is the phrasing the skill was written against. Your own words work too.

The agent will inspect your language, dependencies, context assembly, model-call
boundary, async lifecycle, tests, configuration and telemetry, then choose the
narrowest integration that fits: the Python or TypeScript SDK, a LangChain or
LangGraph middleware, a LiteLLM guardrail, a LlamaIndex postprocessor, or direct
HTTP for anything else.

## What the skill will not do

These are binding, and they are the reason to use the skill rather than wiring
it by hand from the API reference:

* **It pins an operating point.** Selection behaviour is frozen to the label you
  name. See [what a label pins](/concepts/operating-points#what-a-label-pins-and-what-it-cannot).
* **It starts in shadow.** Nothing changes what your model receives until you
  turn selection on in configuration. See [Shadow mode](/concepts/shadow-mode).
* **It fails open, exactly.** Your original context is preserved byte for byte on
  a stand-down, a shadow run, a timeout, an HTTP failure, a malformed response,
  and on any outcome it does not recognise. See
  [the two cases that are not errors](/errors#the-two-cases-that-are-not-errors).
* **It keeps mandatory context out of selection.** System instructions, safety
  policy, tool schemas and the current user turn are concatenated around the
  selected block, never submitted for selection. See
  [if a record must not be dropped](/api-reference/introduction#fields-with-no-effect).
* **It emits metadata only.** Counts, outcomes, latencies and identifiers. Never
  prompts, context, excerpts, credentials, or raw errors that may carry your
  customers' input. See [Retention and trust](/retention-and-trust).

## Verifying it worked

Shadow mode gives you the numbers before you change any behaviour:

* **Applied versus passed through**: through an SDK, the skill gates on
  `result.applied` and passes your exact original context whenever it is false.
  On raw HTTP the equivalent signal is the top-level `outcome`, never
  `gate.engaged` ([why](/errors#reading-a-stand-down)).
* **Token reduction**: `tokens_before`, `tokens_after` and `reduction_ratio`, on
  the engine's own accounting, which is not your provider's billed token count.
  See [How to recompute your own bill](/billing/recompute-your-bill).
* **Latency**: `engine_latency_ms` on each response.

## Versions

Skill releases carry their own version, separate from the SDK and from the API.
A skill release names the SDK range it writes against and the operating point it
pins, and **a new operating point is never introduced by an update**: changing
the pinned label is a new major version of the skill, so an update cannot
silently move your selection behaviour.