For the complete documentation index, see llms.txt. This page is also available as Markdown.

Install the LearnCard Skill

Install the LearnCard skill so Claude Code, Cursor, Codex and other coding agents can set up an issuer, send credentials and call the LearnCard API safely on staging.

Coding agents such as Claude Code, Cursor and Codex can drive the LearnCard CLI for you: create a staging issuer, send and track credentials, create API tokens, and reach SDK methods and REST routes the CLI has no command for. The LearnCard skill is a short operating guide that tells the agent how to do this safely. Install it into your project once, and the agent loads it whenever a task involves LearnCard.

~5 min ยท Needs Node.js 20+. Related: Use LearnCard from an AI Agent ยท Test Safely ยท CLI reference

Install the skill

Run this from your project's root folder. It only writes files; it does not create a LearnCard identity or contact the network.

npx @learncard/cli skill install

By default the CLI looks for .claude/, .cursor/ and .agents/ folders in the current folder and installs for each one it finds. If it finds none, it installs for Claude Code. Choose explicitly with --target:

Agent
Command
File written

Claude Code

npx @learncard/cli skill install --target claude

.claude/skills/learncard/SKILL.md

Cursor

npx @learncard/cli skill install --target cursor

.cursor/rules/learncard.mdc

Codex and other agents using .agents

npx @learncard/cli skill install --target agents

.agents/skills/learncard/SKILL.md

All of the above

npx @learncard/cli skill install --target all

All three files

  • Claude Code loads project skills from .claude/skills/. To make the skill available in every project, install it into your home folder instead: npx @learncard/cli skill install --target claude --dir ~.

  • Cursor gets the same text as a project rule with a description and alwaysApply: false, so Cursor attaches it when a request is about LearnCard.

  • Codex and other agents: if your agent does not load skills from .agents/skills/, add one line to your AGENTS.md: For LearnCard tasks, follow .agents/skills/learncard/SKILL.md.

Other options:

  • --dir <path> installs into another project folder.

  • --print prints the skill instead of writing it, for agents that take instructions some other way.

  • Re-running is safe: an identical file is left alone. If the file differs (you edited it, or a newer CLI has a newer skill), the command stops with code EXISTS. Add --force to overwrite it.

Commit the installed file so everyone on the team, and their agents, get the same rules.

Work staging-first

The skill tells the agent to work this way. It helps to say it in your prompt too:

  1. Use a dedicated folder per network, outside your app's source tree, for example learncard-staging/. The CLI keeps the issuer identity in that folder's .env.

  2. Pass --network staging to every command until you decide to go live. Staging profiles are separate from production, and staging credentials appear only in the staging LearnCard app. Send tests to your own address, or add --suppress-delivery to skip the claim email.

  3. Discover before acting. The agent runs npx @learncard/cli commands --json and npx @learncard/cli capabilities --json to see every command, whether it reads or writes, and which SDK methods and REST routes cover the rest of LearnCard.

  4. Confirm before anything irreversible. The agent should ask you before sending a credential, revoking one, creating an API token, applying an org spec, or doing anything on production. call and api refuse to change state unless the agent passes --write, and --dry-run shows what would happen first.

  5. Keep secrets out of the chat. The agent should never print .env, the seed or an API token.

A good first prompt:

Set up a LearnCard issuer on staging in a new folder learncard-staging, send a test badge to my address with delivery suppressed, and show me its status. Ask me before you send anything.

When you're ready for production, see Go to Production.

What's in the skill

This is the exact file the CLI installs (for Cursor, only the frontmatter differs):

Last updated

Was this helpful?