Skip to main content
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. 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

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:
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.

​
Your first integration

With the skill installed, ask for the integration in your own words. Naming the operating point is worth doing explicitly:
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.
  • It starts in shadow. Nothing changes what your model receives until you turn selection on in configuration. See 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.
  • 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.
  • 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.

​
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).
  • 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.
  • 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.