Everyone's running into the same frustration with AI coding agents right now: they generate code that looks right but breaks because they're working from outdated training data. You'll ask Cursor to set up your SDK and it'll use a pattern that got deprecated six months ago, or GitHub Copilot will suggest an API method that doesn't exist anymore. Setting up agent skills gives your coding assistant structured instructions it can check before generating code, so instead of guessing based on old examples, it follows current patterns that actually work. It's like handing your agent a constantly updated rulebook for each tool you use.

TLDR:

• Agent skills are structured knowledge packages that teach AI coding agents current implementation patterns for specific tools, fixing the problem of outdated training data

• Install skills once and they work across Claude Code, Cursor, GitHub Copilot, and other agents thanks to the open standard adopted by Microsoft, OpenAI, and Anthropic

• Skills use progressive disclosure: agents load only relevant instructions per task, keeping context windows clean even with dozens installed

• Velt ships four agent skills modules (108 total rules) covering setup, comments, CRDT editing, and notifications so developers get working collaboration code on the first try

What Are Agent Skills

Agent skills are structured knowledge packages that teach AI coding agents how to use specific tools or frameworks. When coding with Claude Code, Cursor, or GitHub Copilot, these agents often rely on training data that may be outdated. Skills fix this by providing current instructions, code examples, and rules that agents reference on demand. Each skill contains a SKILL.md file that acts as a rulebook, showing the agent exactly how to write code for a particular task. The file includes correct implementation patterns, common mistakes to avoid, and priority levels for each rule so the agent knows what matters most. Skills can also bundle scripts, configuration files, and other resources needed to generate working code. When you ask your coding agent to build a feature, it checks for relevant skills and follows those instructions.

How Agent Skills Work

When you install a skill, your AI coding agent doesn't load all its contents immediately. Skills use a progressive disclosure system that keeps context windows clean:

• The agent first sees lightweight metadata: the skill's name and description. If you're building a login feature, the agent scans installed skills and spots one called "auth-best-practices." At this point, it hasn't read the actual rules yet.

• Once the agent determines a skill is relevant, it loads the full SKILL.md file. Now it has access to implementation rules, code snippets, and priority markers. The agent references these instructions while generating code, following patterns marked as CRITICAL first.

If the skill includes supporting resources like templates, config files, or scripts, the agent accesses those only when specific rules call for them.

The SKILL.md File Format

A SKILL.md file consists of two sections: YAML frontmatter wrapped in triple dashes, followed by a markdown body.

The frontmatter requires two fields. The name field acts as the identifier (for example, "velt-setup-best-practices"). The description field tells the agent what the skill does and when to trigger it. Write descriptions that cover both function and context: "Guides setup and configuration of Velt SDK authentication, including JWT tokens and document initialization for Next.js and React apps."

The markdown body provides your implementation guidance. Structure it with clear headers, numbered steps for sequential tasks, and code blocks showing correct patterns. Each instruction should include a priority level (CRITICAL, HIGH, MEDIUM, LOW) so agents know execution order. You can include anti-patterns: "Don't initialize the VeltProvider inside a useEffect. Do initialize it at your app root."

Supporting files like scripts or config templates sit in the same directory and get referenced by relative path in the markdown.

The Open Agent Skills Standard

Anthropic released Agent Skills as an open specification, and the industry responded quickly. Microsoft, OpenAI, Atlassian, Figma, Cursor, and GitHub adopted the standard, meaning skills written once work across all their coding agents. This portability removes vendor lock-in. A skill you write for Claude Code will function in GitHub Copilot without modification. You're not investing effort into a proprietary format that traps you with one vendor. If you switch agents later, your skills library transfers with you.

Organizations gain a distribution channel. When you publish a skill for your SDK or API, it works for developers using any compatible agent. You document implementation patterns once and reach users across VS Code, Cursor, and Claude Code at the same time.

The standard creates network effects for knowledge sharing. Teams build internal skills for their architecture patterns, then share them across departments using different AI coding tools.

Installing and Using Agent Skills

Because of that open standard, cross-compatibility of agent skills means you install once and get consistent behavior regardless of which agent you're using.

Installation happens in two ways. Project-level skills live in .github/skills/ or .claude/skills/ directories at your repo root, making them available to anyone working on that codebase. Personal skills go in ~/.claude/skills/ or ~/.copilot/skills/ on your machine, applying to all your projects.

Once installed, agents scan skill descriptions when you make a request. If you ask to set up comments, the agent loads the relevant skill. Other skills stay dormant, keeping your context window focused. You can install dozens of skills without performance penalties because agents load only relevant ones per task.

Creating Custom Agent Skills

Creating a skill starts by documenting tasks you've corrected multiple times. When you repeatedly explain how to use your API or framework, turn that into a reusable skill. Here are the basic steps to follow:

• Create a directory with a SKILL.md file. The frontmatter requires a unique name and description that acts as your trigger. Agents scan this description before loading the full skill, so specify both purpose and context: "Configures Redis caching for Next.js apps using our custom wrapper. Use when setting up server-side caching or optimizing API routes."

• Write rules as direct commands. "Set cache TTL to 3600 seconds for user data" beats "Consider caching user data." Number sequential steps and mark priority levels so agents handle breaking changes first.

• Put skills into your skill directory. This directory can include a scripts/ folder for setup commands and a references/ folder for config templates. Reference these by relative path.

• Test by requesting the task without naming the skill. If the agent doesn't activate it, revise your description to include trigger phrases matching how you naturally request that work.

Best Practices for Agent Skills

So building agent skills isn't that hard. Just a big of structure and description in a special file and you've got some skills built. But, not all skill building is created equal! Here are a few best practices to improve the effectiveness of your agent skills:

• Keep each skill focused on a single job. A skill that covers both authentication and database setup will confuse agents about when to activate it. Split broad topics into separate skills so agents load only what's needed.

• Prefer instructions over scripts when explaining how to write code. Agents excel at generating implementations from clear rules. Reserve scripts for tasks requiring deterministic behavior or external tooling, like running linters or updating config files across repos.

• Write imperative steps with explicit inputs and outputs. "Pass the document ID as a string to the setDocument method" works better than "You might want to consider passing a document ID." Include what the agent receives and what it should produce.

• Test your skill by prompting without naming it directly. If "add user presence" doesn't activate your presence skill, revise the description to include terms developers use when requesting that feature.

• Keep SKILL.md files under 500 lines. Move API reference tables, config options, and long code examples to separate markdown files in a references/ directory. Your SKILL.md should guide implementation while reference docs provide lookup details.

Common Use Cases for Agent Skills

Teams use agent skills to codify domain-specific knowledge that agents can't infer from training data alone. Here are the most common applications:

• Code review skills encode review checklists so agents catch issues before humans see them. A skill might flag missing error boundaries in React components or enforce specific logging patterns your team requires.

• API development skills provide exact endpoint structure: authentication headers, response schemas, pagination formats, and error codes your API returns instead of having agents guess REST conventions.

• Framework implementation skills handle specific patterns. A Next.js skill knows to use server actions for mutations, a SvelteKit skill understands load functions, and a React skill enforces your team's hook conventions.

• Test automation skills generate Playwright or Selenium tests following your organization's selectors, wait strategies, and assertion patterns instead of generic examples.

• Security auditing skills based on OWASP guidelines help agents identify vulnerabilities like SQL injection risks or XSS vectors during code generation.

• Documentation skills auto-generate docs matching your style guide for consistency across API references and implementation guides.

• Organizations treat skills as executable tribal knowledge that works at scale across every developer's editor.

Velt Agent Skills for Collaboration Implementation

Velt ships Agent Skills to fix a problem developers face regularly: AI coding agents reference outdated training data about our SDK. When you ask Claude Code or Cursor to add Velt features, agents generate code from deprecated patterns or guess at implementations that break.

Our skills package covers four modules across the collaboration stack. Install with one command:

npx skills add velt-js/agent-skills

npx skills add velt-js/agent-skills

npx skills add velt-js/agent-skills

npx skills add velt-js/agent-skills

Each module targets different features:

Freestyle, Popover, Stream, Text, Page, and Inline comment modes; rich text editor integrations

Every rule carries an impact level: CRITICAL, HIGH, MEDIUM, or LOW. Agents process CRITICAL rules first, preventing breaking mistakes like initializing providers in the wrong scope or skipping required authentication steps.

We version-control these skills alongside SDK releases. When we ship new features or deprecate old patterns, skills update automatically so agents reference current implementations.

Final Thoughts on Building With Agent Skills

Agent skills give you control over what your AI coding agent generates by replacing outdated training data with current instructions. You can install skills for third-party SDKs or write custom ones for your company's architecture patterns. The same skill file works in Cursor, GitHub Copilot, and Claude Code without modification. Book a demo to learn how Velt's skills handle real-time collaboration features. Your agents become more accurate as your skills library grows.

FAQ

How do I install agent skills in my project?

Run npx skills add velt-js/agent-skills in your project directory to install Velt's complete skills package. The skills work immediately with Claude Code, Cursor, GitHub Copilot, and other compatible AI coding agents without additional configuration.

What's the difference between project-level and personal skills?

Project-level skills live in .github/skills/ or .claude/skills/ at your repo root and apply to everyone working on that codebase. Personal skills go in ~/.claude/skills/ or ~/.copilot/skills/ on your machine and apply to all your projects.

When should I create a custom skill instead of writing regular documentation?

Create a skill when you're correcting the same implementation mistake repeatedly across your team. If your AI agent keeps generating outdated patterns for your API or framework, a skill will teach it the correct approach and prevent those errors automatically.

Can I use the same skill files with different AI coding agents?

Yes, agent skills follow an open standard adopted by Microsoft, OpenAI, GitHub, Cursor, and Anthropic. A skill written for Claude Code works in GitHub Copilot without modification, so you're not locked into one vendor's tool.

Why do agent skills use priority levels like CRITICAL and HIGH?

Priority levels tell the agent which rules to process first. CRITICAL rules prevent breaking mistakes like initializing providers in the wrong scope, while LOW priority rules handle style preferences. This ordering helps agents generate working code on the first try.