February 15, 2026·4 min read

Publish Your First Agent Skill in Under 5 Minutes

A step-by-step tutorial for publishing your first reusable agent skill with the localskills CLI. Install it into Cursor, Claude Code, and more.

getting-started

Prerequisites

You need two things:

Node.js 18+ installed on your machine
A localskills.sh account — sign up free at localskills.sh

That's it. The whole process takes under 5 minutes.

Step 1: Install the CLI

npm install -g @localskills/cli

Verify the installation:

localskills --version

Step 2: Authenticate

localskills login

This opens your browser for authentication. Sign in with your Google account, and the CLI is authorized automatically via a secure device code flow.

For CI/CD environments where a browser isn't available, use token-based auth:

# Generate a token in your dashboard at localskills.sh/dashboard/settings
localskills login --token lsk_your_api_token_here

Verify you're logged in:

localskills whoami

Step 3: Create a skill file

Create a markdown file with your AI coding instructions. Here's a practical example:

mkdir -p .cursor/rules

Create .cursor/rules/api-conventions.mdc:

---
description: API route conventions for our Next.js project
alwaysApply: true
---

# API Conventions

## Route structure
Use the Next.js App Router handler pattern. Every route exports
named async functions: GET, POST, PUT, DELETE.

## Response format
Always return JSON with this shape:
- Success: { data: <result> }
- Error: { error: <message> }

## Error handling
Wrap every handler in try/catch. Log errors with the
project logger, never console.log.

## Authentication
Call requireAuth(request) before any data mutation.
Public read endpoints don't need auth.

You can also create plain markdown files in .claude/skills/, .windsurf/rules/, or any other location the CLI scans.

Step 4: Publish to the registry

localskills publish

The CLI scans your project for rules files and shows you what it found:

Scanning project for rules files...

Found 1 file:
  .cursor/rules/api-conventions.mdc

? Select files to publish: (use space to select)
> [x] .cursor/rules/api-conventions.mdc

? Team: my-team
? Name: api-conventions
? Visibility: private
? Type: skill

Publishing api-conventions v1... done!

Your skill is now live in the registry. You can see it in your dashboard.

Publishing options

You can also publish non-interactively:

localskills publish .cursor/rules/api-conventions.mdc \
  --team my-team \
  --name api-conventions \
  --visibility private \
  --type skill \
  -m "Initial version"

Visibility options:

private — only team members can access (default)
public — anyone can discover and install
unlisted — accessible via direct link, not in search

Step 5: Install into your tools

Now any team member can install it:

localskills install my-team/api-conventions

The CLI detects which AI tools are installed and prompts you:

? Select target tools: (use space to select)
> [x] Cursor
  [x] Claude Code
  [ ] Windsurf
  [ ] GitHub Copilot

? Scope: project
? Method: symlink

Installing into Cursor... done!
Installing into Claude Code... done!

Installed my-team/api-conventions v1 into 2 tools.

Or specify everything in one command:

localskills install my-team/api-conventions --target cursor claude --project --symlink

Tell your team to install the CLI and run:

npm install -g @localskills/cli
localskills login
localskills install my-team/api-conventions

That's it. Everyone gets the same rules, in the same format, for their preferred AI tool.

When you update the skill, team members get the latest version with:

localskills pull

If you used symlink installation (the default), the update is automatic — the symlink points to the cached file, and pull refreshes the cache.

Next steps

You've published your first skill. Here's what to explore next:

Versioning: Every publish creates a new version. Roll back from the dashboard if needed.
Visibility: Switch between public, private, and unlisted in the dashboard or with --visibility flag.
Analytics: Track who's installing your skills with download analytics.
Teams: Set up role-based access — owners, admins, members, and view-only roles.
Enterprise: Configure SSO and SCIM directory sync for larger organizations.