Client-side Skills

Beta — This feature is in alpha. APIs may change before stable release.

Client-side skills only support inline source. For file or url sources, use server-side skills.

SkillProvider

Wrap your app inside <CopilotProvider> to enable client-side skills:

import { SkillProvider, defineSkill } from "@yourgpt/copilot-sdk/react";

const brandVoice = defineSkill({
  name: "brand-voice",
  description: "Ensures responses match our brand tone and terminology",
  strategy: "eager",
  source: {
    type: "inline",
    content: "Always respond in a friendly, concise tone. Use 'we' not 'I'. Avoid jargon.",
  },
});

const codeReview = defineSkill({
  name: "code-review",
  description: "Performs structured code reviews with actionable feedback",
  strategy: "auto",
  source: {
    type: "inline",
    content: "When reviewing code: 1) Check for bugs first...",
  },
});

export default function App() {
  return (
    <CopilotProvider widgetToken="...">
      <SkillProvider skills={[brandVoice, codeReview]}>
        <YourApp />
      </SkillProvider>
    </CopilotProvider>
  );
}

useSkill

Register a skill from deep inside the component tree. It activates on mount and cleans up on unmount — useful for page-scoped skills.

import { useSkill } from "@yourgpt/copilot-sdk/react";

function CheckoutPage() {
  useSkill({
    name: "checkout-flow",
    description: "Guides the user through the checkout process step by step",
    strategy: "auto",
    source: {
      type: "inline",
      content: `
## Checkout Assistant

When the user asks about checkout:
1. Confirm their cart items
2. Check for applicable promo codes
3. Walk through shipping options
4. Confirm payment method before submitting
      `,
    },
  });

  return <CheckoutUI />;
}

The skill is automatically unregistered when CheckoutPage unmounts.

If an inline skill exceeds 2000 characters in development, a console warning is shown. Large inline skills are sent on every request — consider using a server-side file skill instead.

defineSkill

Type-safe factory for creating skill definitions. An identity function with TypeScript inference:

import { defineSkill } from "@yourgpt/copilot-sdk/react";

const mySkill = defineSkill({
  name: "api-docs-helper",
  description: "Helps users understand and use the Acme API",
  strategy: "auto",
  version: "2.0.0",
  source: {
    type: "inline",
    content: "When explaining API endpoints, always include example requests...",
  },
});

// Reuse in multiple providers
<SkillProvider skills={[mySkill]} />

useSkillStatus

Observe the live skill registry from any component inside <SkillProvider>:

import { useSkillStatus } from "@yourgpt/copilot-sdk/react";

function DebugPanel() {
  const { skills, count, has } = useSkillStatus();

  return (
    <div>
      <p>{count} skill(s) active</p>
      {has("code-review") && <Badge>Code Review</Badge>}
      <ul>
        {skills.map((s) => (
          <li key={s.name}>
            {s.name} ({s.strategy ?? "auto"})
          </li>
        ))}
      </ul>
    </div>
  );
}

Return type

interface UseSkillStatusReturn {
  skills: ResolvedSkill[];          // All currently registered skills
  count: number;                    // Number of registered skills
  has: (name: string) => boolean;   // Check if a named skill is active
}

Type Reference

type SkillStrategy = "eager" | "auto" | "manual";

interface SkillDefinition {
  name: string;
  description: string;
  source: { type: "inline"; content: string };
  strategy?: SkillStrategy; // default: "auto"
  version?: string;
}