Use your coding agent

The northlight skill teaches a coding agent the whole path in the quick setup: the commands, the console fields, the code patterns and the rules. npx @north-light/sdk init installs it into your project. The skill needs no account and no crtr.

Install it

For a new app, init installs it with everything else:

npx @north-light/sdk@latest init my-app

For a project that already has a package.json, run npx @north-light/sdk init in it. It adds @north-light/sdk at an exact version, makes a key if local/app-key.json does not exist, installs the skill, and writes no app code. It never overwrites a file: if one is in the way, it names the file and exits non-zero.

To install only the skill, or to replace an older copy:

npx @north-light/sdk skill

skill always replaces the northlight skill it finds. --print writes the skill to stdout instead of to files.

Where it goes

--agent claude, --agent agents or --agent all (the default) picks which. all writes both places. Cursor and Copilot also read .claude/skills, so they may list the skill twice. Use --agent agents or --agent claude to write one place. init takes --global-skill where skill takes --global.

The project copy is the default so it is committed with the project, and teammates get it from git. It matches the SDK version your project pins.

Checked: the files init writes, and that skill rewrites both, from the SDK source built on this branch. Which agent loads which directory is from each agent's documentation and is not yet checked on production for every agent.

Without a project: the hosted skill

An agent that has no project yet can read the hosted copy:

Read https://sdk.docs.northlight.ai/SKILL.md and follow it.

The agent runs npx @north-light/sdk@latest init and then follows the quick setup. It asks you to do the browser steps: sign up, register the app at https://account.northlight.ai/console/new, and add permissions. The hosted copy matches the SDK version the docs site was last built from.

How it stays current

The skill's frontmatter carries metadata.sdk-version. Its first instruction tells the agent to compare that number with node_modules/@north-light/sdk/package.json. If they differ, the agent runs npx @north-light/sdk skill, which rewrites the skill from the installed package. A skill therefore always documents the SDK your project pins, and a newer SDK never gets documented against an older one.

Example prompts

After init:

Add a "Summarize my day" button to the app. It starts a run on the signed-in person's runtime with runs.start, waits with runs.wait, and shows the report. Use the northlight skill.

Starting from nothing:

Read https://sdk.docs.northlight.ai/SKILL.md and build me an app where people sign in with Northlight and the app texts them a daily summary. Tell me which console steps I need to do.

Rules the skill gives your agent

Your agent reads them from the skill. They are worth knowing as the person reviewing its work:

• Pin the exact SDK version.
• Take scope strings from the console's Add permissions list, never from memory.
• Never print, paste or commit local/app-key.json.
• Reach a person's runtime with oauth.client(userId), not new Crouter().
• Use a persistent ConnectionStore in production.
• Get data back with runs.parse, not by reading runs.trace.