What Are Agent Skills? The Missing Layer for AI Coding

What are agent skills?

Agent skills are persistent, reusable instructions that teach AI coding assistants how to work with your codebase. They encode your team's patterns, conventions, and domain knowledge into files that AI tools read before generating code.

If you've written a .cursorrules file, a CLAUDE.md, or a .windsurfrules — you've already written agent skills. The concept isn't new. What's new is treating them as a first-class, shareable, versioned artifact — the same way we treat npm packages or Docker images.

Skills vs prompts: why persistence matters

When you type instructions into a chat window — "use TypeScript strict mode, follow our API conventions" — those instructions vanish after the conversation ends. The next session starts from zero.

Agent skills eliminate the "did you remember to tell the AI about our conventions?" problem. They're always there, always applied, always consistent.

Skills vs rules: what's the difference?

In localskills.sh, content is categorized as either a skill or a rule:

Skills are capabilities and workflows:

• How to structure API routes in your framework
• Testing patterns and conventions
• Component architecture guidelines
• Deployment and CI/CD instructions

Rules are constraints and governance:

• Security requirements (never log PII, always validate input)
• Code style enforcement (naming conventions, file structure)
• Dependency policies (approved libraries, version constraints)
• Compliance requirements (data handling, access control)

Both are markdown files with the same lifecycle — versioning, visibility control, team sharing. The distinction helps organize your instructions: skills teach the AI how to do things, rules tell it what it must and must not do.

On Claude Code specifically, skills install to .claude/skills/ and rules to .claude/rules/, matching Claude Code's native directory structure.

The agent skills lifecycle

1. Write

Start with a markdown file describing one focused topic:

# API Route Conventions

## Pattern
Every API route uses the Next.js App Router handler pattern:

export async function POST(request: Request) {
  const body = await request.json();
  // validate, process, return
  return Response.json({ data: result });
}

## Error handling
Always wrap handlers in try/catch.
Return { error: message } with appropriate HTTP status.

## Authentication
Check auth before any data mutation.
Use the requireAuth() helper from lib/auth.

2. Publish

Upload to the registry with the localskills CLI:

localskills publish api-conventions.md --team my-team --name api-conventions

The skill gets a unique slug, version number, and content hash. It's stored securely and only accessible to your team (or publicly, if you choose).

3. Install

Any team member installs it into their preferred AI tool:

# Install into Cursor and Claude Code
localskills install my-team/api-conventions --target cursor claude

The CLI places the right file in the right location for each tool. Symlinks by default — so updates propagate automatically.

4. Update

When conventions change, publish a new version:

# Edit the skill locally, then re-publish
localskills publish api-conventions.md --team my-team --name api-conventions -m "Added rate limiting section"

Every team member gets the update with localskills pull. Old versions are preserved — you can roll back from the dashboard at any time.

Examples of effective agent skills

Tech stack skill

# Tech Stack

- Framework: Next.js 15 (App Router, Server Components)
- Language: TypeScript 5.7 (strict mode, no any)
- Database: PostgreSQL with Drizzle ORM
- Auth: NextAuth v5 with Google OAuth
- Styling: Tailwind CSS v4 (no CSS modules)
- Testing: Vitest + React Testing Library
- Package manager: pnpm

Code review skill

# Code Review Checklist

When reviewing code, verify:
- Types are explicit (no implicit any)
- Error handling exists for all async operations
- Database queries use parameterized inputs
- New API routes include auth checks
- Tests cover the happy path and at least one error case
- No console.log statements (use the logger utility)

Naming conventions rule

# Naming Conventions

- Files: kebab-case (user-profile.tsx, not UserProfile.tsx)
- Components: PascalCase exports (export function UserProfile)
- Variables: camelCase
- Database columns: snake_case
- API endpoints: kebab-case (/api/user-profiles)
- Environment variables: UPPER_SNAKE_CASE

Why every team needs a skills registry

Without a centralized registry, agent skills drift. Each developer maintains their own version. New hires don't know the right files exist. When conventions change, some repos get updated and others don't.

A skills registry gives you:

• Single source of truth — one authoritative version of each skill
• Version history — see what changed and when, roll back if needed
• Access control — team roles determine who can publish vs install
• Analytics — track adoption across your organization
• Cross-tool support — same skill works in Cursor, Claude Code, Windsurf, Copilot, and more

Getting started with localskills.sh

localskills.sh is the registry for agent skills. Publish, share, and install skills across 8 AI coding tools with a single CLI.

# Install
npm install -g @localskills/cli

# Authenticate
localskills login

# Publish your existing rules files
localskills publish

# Install a skill into your tools
localskills install your-team/api-conventions --target cursor claude windsurf

Read the full documentation or follow the 5-minute publishing tutorial.