# Install a Skillnai skill into your AI agent

This guide is written for an AI coding agent (Claude Code, Cursor, Codex, Gemini CLI or OpenCode). Read the whole file, detect which agent you are running in, install the requested skill into that agent's native skills directory, run the doctor check, and verify with a short test run.

Free skills install without login. Premium skills show the same copyable commands, but open a browser sign-in on first install. **Never ask for, echo, store or print credentials.**

## 1. Detect the agent

Ask the user which agent they are using if it is ambiguous. Otherwise use the running client or environment hints below.

| Agent | ID for `--agent` | Typical install directory | Detection hints |
| --- | --- | --- | --- |
| Claude Code | `claude-code` | `~/.claude/skills` | Running inside Claude Code / `CLAUDECODE` env |
| Cursor | `cursor` | `~/.cursor/skills` | Running inside Cursor / Cursor shell integration |
| Codex | `codex` | `~/.agents/skills` | Running inside Codex CLI |
| Gemini CLI | `gemini-cli` | `~/.gemini/skills` | Running inside Gemini CLI |
| OpenCode | `opencode` | `~/.agents/skills` | Running inside OpenCode |

If you cannot confidently detect the agent, ask one short question: "Which agent should I install this for: Claude Code, Cursor, Codex, Gemini CLI or OpenCode?" Do not guess and install into the wrong directory.

## 2. Install the skill

Use the CLI with the matching agent flag. Replace `<slug>` with the skill ID from the request.

```bash
npx skillnai add <slug> --agent <agent>
```

Examples:

```bash
npx skillnai add launch-film --agent claude-code
npx skillnai add data-story --agent cursor
npx skillnai add carousel-cards --agent codex
npx skillnai add keynote-deck --agent gemini-cli
npx skillnai add cover-kit --agent opencode
```

The CLI writes the skill into the directory shown in the table above. It does not modify files outside that target and it does not write credentials to disk.

If `npx` is unavailable, stop and tell the user what is missing. Do not install Node or other system packages without explicit permission.

## 3. Run the doctor check

```bash
npx skillnai doctor <slug>
```

The doctor verifies:

- Node and the render pipeline
- ffmpeg for video skills
- Chrome for HTML/Remotion/HyperFrames rendering
- Read/write permissions on the install directory
- The SKILL.md frontmatter and declared formats
- Whether optional environment variables exist (it reports presence only, never values)

If the doctor reports a missing required dependency, report it to the user with the exact tool name. Do not silently install or upgrade system tools.

## 4. Verify the install

1. Confirm the skill appears in the agent's skill list.
2. Confirm the skill directory exists under the install directory from the table.
3. Run a short test, ideally in the vertical format:

```text
Use <slug> to make a 5-second 9:16 test and show me where the output is saved.
```

Check that:

- The render finishes without missing-dependency errors.
- Captions, titles and CTAs stay inside the 9:16 safe zones.
- No local file paths, tokens or other secrets appear in the frames or logs.
- The output is written to the location the skill reports.

## 5. Free vs premium

- **Free skills:** no login needed. Copy the prompt or run the install command as-is.
- **Premium skills:** the install command is still visible and copyable. On the first run, your browser opens a sign-in page for the user to complete. The CLI stores a local session token; it never asks the agent for a password.

Never invent a license key, never ask the user to paste one into the chat, and never write tokens into a prompt, SKILL.md, source file or commit.

## Credential rules for the agent

- Never ask for API keys, passwords, cookies, session tokens or `.env` contents.
- Never read, print, copy or transmit `.env` files or shell history.
- If an optional dependency such as `FAL_KEY` is needed, ask the user to set it in their own environment, then confirm only that it exists (`test -n "$FAL_KEY"`), never its value.
- Never place credentials in command arguments where they would be logged.
- If the user offers credentials unprompted, decline to echo them and suggest setting them as environment variables instead.

## Updating and removing

```bash
npx skillnai update <slug>
npx skillnai remove <slug>
```

Removing a skill only deletes its install directory. It does not log the user out and does not delete generated media.

## Troubleshooting

- **`command not found: npx`** — Node.js is not installed or not on PATH. Ask the user to install Node 20+.
- **Doctor says ffmpeg or Chrome is missing** — report the missing tool and the platform-specific install hint. Do not install it silently.
- **Permission denied in the skills directory** — ask before changing permissions; never use broad `chmod 777`.
- **Premium tool returns 401/403** — ask the user to complete browser sign-in, then retry. Do not request their password or token.
- **The skill is not listed after install** — confirm the agent flag matches the directory in the table and restart the agent.

## Machine-readable entry point

- Site: https://skillnai.com
- Skill library: https://skillnai.com/skills
- Per-skill install docs: https://skillnai.com/skills/<slug>/install.md
- llms.txt: https://skillnai.com/llms.txt

You are done when the doctor passes, the skill is visible to the agent, and a short test render exists.