create-provider-package-with-core

Original：🇺🇸 English

Translated

Use when building a custom provider integration on top of @prefactor/core so your app can instrument agent, llm, and tool workflows without relying on a prebuilt adapter package.

2installs

Sourceprefactordev/typescript-sdk

Added on2026-02-26

NPX Install

npx skill4agent add prefactordev/typescript-sdk create-provider-package-with-core

SKILL.md Content

View Translation Comparison →

Create Provider Package With Core

Build your own provider adapter package on top of

@prefactor/core

.

Core principle:

@prefactor/core

handles tracing infrastructure, while your adapter maps provider-specific APIs.

Trigger Phrases

Apply this skill when the request includes patterns like:

"add a new provider package"
"instrument provider X using @prefactor/core"
"my framework does not have a Prefactor adapter"
"build a custom SDK integration with Prefactor"

Workflow

Define adapter boundaries.
Create a small adapter package in your project.
Implement instrumentation with core primitives.
Validate trace behavior in your app.
Harden for production usage.

1) Define adapter boundaries

Keep your adapter thin: request/response mapping, middleware hooks, payload adaptation.
Reuse
```
@prefactor/core
```
for lifecycle, context, serialization, and transport behavior.

Use provider-prefixed span types (

<provider>:agent

,

<provider>:llm

,

<provider>:tool

).

2) Create a small adapter package

In your app or workspace, create a dedicated module/package (for example

prefactor-provider-<provider>

):

```
src/index.ts
```
public entrypoint
```
src/<provider>-middleware.ts
```
provider integration wrapper
```
tests/
```
covering tracing behavior
```
package.json
```
with dependency on
```
@prefactor/core
```

Use this package surface:

ESM imports/exports; explicit
```
.js
```
on relative imports.
Export only stable adapter entrypoints from
```
src/index.ts
```
.

3) Implement instrumentation with core primitives

Depend on
```
@prefactor/core
```
for tracing, context propagation, config, transport helpers.
If your adapter exposes helper APIs like
```
init
```
+
```
withSpan
```
, keep them bound to the same tracer source; if calling core
```
withSpan
```
outside adapter helpers, pass an explicit tracer.
Wrap provider execution paths in context (
```
SpanContext.runAsync(...)
```
) so parent/child spans remain intact.
Capture inputs/outputs and usage metadata when available; apply truncation/redaction safeguards.
On errors, record span failure data and rethrow the original error.
For streaming providers, finish spans on completion, cancellation, and stream errors.

4) Validate trace behavior in your app

Validate in integration tests or a local smoke script:

parent/child span relationships
success + error span completion
streaming completion/cancel/error terminal paths
payload capture and limits
provider-prefixed span types

Confirm telemetry is emitted through your configured Prefactor transport.

5) Harden for production usage

Before rollout, verify:

instrumentation never crashes user requests
spans finish exactly once
secrets are redacted and payloads are bounded
errors preserve original stack/type when rethrown

Quick Reference

Decision	Put it where
Reusable tracing/context helpers	`@prefactor/core`
Provider request/response mapping	your adapter package
Span lifecycle logic	`@prefactor/core` + thin wrapper calls
Provider-only middleware/wrappers	your adapter package

References

Use

references/provider-package-checklist.md

for an implementation checklist.

Common Mistakes

Re-implementing tracing lifecycle per provider instead of reusing core.
Using generic span names instead of provider-prefixed types.
Capturing raw payloads without truncation/redaction.
Swallowing provider errors after instrumentation.