SkillValit Documentation

Everything you need to manage and install AI Agent Skills.

Getting Started

SkillValit is a registry for AI Agent skills — reusable prompt templates and tools that train agents like Claude, Gemini, Codex, and generic .agents/ tools.

1. Create a Workspace

2. Authenticate the CLI

The easiest way to authenticate is a one-time browser login:

npx skillvalit login

This opens the SkillValit approval page in your browser (an RFC 8628 device flow). Confirm that the code shown in your terminal matches the one on the page, click Approve, and the CLI saves a credential to ~/.skillvalit. After that, add and add-set need no --key. The stored token is valid for 30 days — run skillvalit login again to refresh it.

The credential file is written with user-only permissions (0600 on macOS/Linux; a restricted ACL via icacls on Windows), and the token itself is never shown in the browser — it is delivered only to your terminal after you approve.

When you are done, revoke the login and delete the local credential with:

skillvalit logout

Using an API Key Instead (CI / scripting)

For non-interactive environments where a browser login isn't possible, use a workspace-scoped API key. Navigate to Settings and find the Telemetry Registry Bearer Token block — view or regenerate your API key there. Pass it via the --key flag or the AGENT_VAULT_KEY environment variable.

When resolving credentials, the CLI uses the first of these that is present, in priority order: the --key flag, then AGENT_VAULT_KEY, then a stored skillvalit login, then an interactive prompt.

3. Install a Skill via CLI

No install required — run the CLI directly:

npx skillvalit add my-org/my-skill --key YOUR_API_KEY

The same works with bunx skillvalit add my-org/my-skill --key YOUR_API_KEY or pnpm dlx skillvalit add my-org/my-skill --key YOUR_API_KEY.

Developing against a local checkout? Install the CLI globally with npm install -g ./cli, then run skillvalit add my-org/my-skill --key YOUR_API_KEY directly.

Install a Whole Skill Set (add-set)

add-set installs every non-deleted skill in a skill set at once. Skill set names can contain spaces, so quote the <org>/<set> path:

skillvalit add-set "my-org/my-set" --key YOUR_API_KEY

Or via npx: npx skillvalit add-set "my-org/my-set" --key YOUR_API_KEY. Takes the same --key and -t options as add.

Choose an Install Target

Use -t, --target <target> to control where the skill lands: agents, claude, gemini, or codex, writing into .agents/skills/, .claude/skills/, .gemini/skills/, or .codex/skills/ respectively, each as <skill-id>/SKILL.md. Omit -t and the CLI shows an interactive picker instead. Applies to both add and add-set.

Zero-Dependency Install (curl | sh)

No CLI install needed — pipe the install script directly to sh:

curl -H "Authorization: Bearer $AGENT_VAULT_KEY" \ https://skill-valit.vercel.app/api/my-org/skill/my-skill/install | sh

Specify a target tool with ?tool= (defaults to agents):

curl -H "Authorization: Bearer $KEY" \ 'https://skill-valit.vercel.app/api/my-org/skill/my-skill/install?tool=claude' | sh

If you omit --key, the CLI falls back to a stored skillvalit login (see CLI Authentication), the AGENT_VAULT_KEY environment variable, or an interactive prompt — in that order.

4. Set the Server URL

By default the CLI connects to https://skill-valit.vercel.app. Set AGENT_VAULT_URL to change the target server (e.g. for local development).

Authoring Best Practices

Well-authored skills are reusable, composable, and easy to maintain. Follow these guidelines when writing a skill's definition (the SKILL.md body — the coreInstructions field under the hood).

Structure Your Instructions

Every SKILL.md body follows the same shape: an # <Skill Name> Skill title, a one-line intro sentence, a ## Core Mandates section written as bolded bullet points, and one or more workflow/output sections such as ## Implementation, ## Validation, or ## Guidelines. The ## Implementationsection holds a fenced code block containing the actual system prompt text — that's where the agent's instructions live. Keep Core Mandates generic and composable so the skill stays reusable across contexts, rather than hard-coding one-off specifics. Here's the Email Triage starter template as an example:

# Email Triage Skill

Expert-level email categorization and prioritization skill for high-volume corporate environments.

## Core Mandates
- **Categorization:** Classify into Support, Sales, Internal, or Spam.
- **Prioritization:** Assign score 1-5 based on urgency and impact.
- **Extraction:** Identify Order IDs, Customer Names, and Deadlines.

## Implementation
```markdown
You are an expert email triage assistant. Your goal is to:
1. Categorize incoming emails.
2. Assign a priority score.
3. Extract core entities.
4. Generate a concise summary.
```

## Validation
- Verify email headers for routing information.
- Check sentiment to adjust priority.

Version Your Skills

Use semantic versioning (v1.0.0, v1.1.0) and update the version field whenever you change coreInstructions. Note that every save automatically snapshots a new SkillVersion regardless — manual semver labels are for humans, not a requirement for history to be kept.

Organize with Skill Sets

Group related skills into Skill Sets(e.g., “Data Analysis”, “DevOps”). This makes discovery easier in the Skill Registry.

Write Good Descriptions

The description field appears in search results and the CLI. Keep it concise but informative — one sentence that explains what the skill does.