Agent skill

AI agents

One command teaches Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and other coding agents how your secrets work, and that they never get to see them.

npx msecrets skill
git add .claude/skills .agents/skills

What the agent learns

msecrets ships an Agent Skill: instructions that coding agents load when a task touches secrets. Agents that have it:

Code

Use the typed SDK

They read secrets through createClient(file) from one module, handle secrets that only some environments have, and treat a type error as a missing secret instead of casting it away.

Hands off

Never see a value

They never run get, export, or the terminal UI, never ask you to paste a secret, and never edit msecrets.json by hand. They only run ls and check, which need no key.

Guide

Tell you what to run

When code needs a new secret, they give you the exact msecrets set command for your terminal, and explain joining, access, and deployment when you ask.

They also know how to wire injectEnv for libraries that read process.env, write tests with fake secrets instead of real ones, set up a machine key for a deployment, and what each SDK error means.

The rules are instructions, not a sandbox: an agent that can run commands as you can technically run msecrets get with your key. Keep agents that run unattended on machines without your msecrets key.

Install

In your project (recommended)

npx msecrets skill

This writes the skill to .claude/skills/msecrets/SKILL.md (Claude Code) and .agents/skills/msecrets/SKILL.md (Codex, Cursor, GitHub Copilot, Gemini CLI, and other agents that read .agents/skills) at the root of your git repository. Commit both, and every teammate’s agent knows msecrets. The skill comes from the installed @msecrets/ui, so it always matches your version; run npx msecrets skill again after upgrading.

For yourself, in every project

npx msecrets skill --global       # ~/.claude/skills and ~/.agents/skills

Other ways

npx skills add k18k/msecrets      # the skills CLI, for many more agents

In Claude Code, as a plugin that updates with the repository:

/plugin install msecrets --marketplace k18k/msecrets

npx msecrets skill --print prints the skill, for agents with their own instruction files.

Working with an agent

You keep the values; the agent writes the code. A typical change:

You: “Send error reports to Sentry in staging and production.”

The agent adds secrets.SENTRY_DSN handling to the code (it is string | undefined once scoped) and asks you to run:

npx msecrets set SENTRY_DSN --env staging
npx msecrets set SENTRY_DSN --env production
npx msecrets scope SENTRY_DSN staging production

You run them in your terminal; the prompt hides what you type. The agent runs npx msecrets check, and you commit msecrets.json with the code.

Values that nobody needs to know, like a random session key, the agent can generate and pipe straight into msecrets set so the value is never printed.

What is in the skill

The full text is packages/ui/skills/msecrets/SKILL.md. It is plain Markdown: read it to know exactly what your agents are told.