onboarding - SKILL.md Agent Skill

name: onboarding description: >- How to register user-facing setup steps (API keys, OAuth, connecting third-party services) for the sidebar setup checklist. Use when adding a feature that needs initial user configuration. scope: dev metadata: internal: true

Onboarding Steps

Rule

If a feature requires user-facing setup (API keys, OAuth, connecting a third-party service), register an onboarding step so it appears in the agent sidebar's setup checklist.

Onboarding must point users to a secure credential path; it must never encode the credential value in source, docs, fixtures, prompts, or generated content. For API keys and service tokens, prefer registerRequiredSecret() from the secrets skill so the settings UI, encrypted storage, validation, and onboarding checklist stay in one place. For OAuth, check the scoped OAuth token store. Use deployment env vars only for deploy-level configuration, not per-user credentials.

Registering a Step

import { registerOnboardingStep } from "@agent-native/core/onboarding";
import { hasOAuthTokens } from "@agent-native/core/oauth-tokens";

registerOnboardingStep({
  id: "gmail",
  order: 100,
  title: "Connect Gmail",
  description: "Grant read/send access.",
  methods: [
    {
      id: "oauth",
      kind: "link",
      primary: true,
      label: "Sign in with Google",
      payload: { url: "/_agent-native/google/auth-url" },
    },
  ],
  isComplete: async (ctx) =>
    ctx?.userEmail ? hasOAuthTokens("google", ctx.userEmail) : false,
});

See packages/core/docs/content/onboarding.md for method kinds and built-in steps.

Related Skills

adding-a-feature — The four-area checklist; onboarding is often part of a new integration
authentication — Most onboarding steps involve OAuth or credentials