>_ skills-hub.ai
Back to blog

Building Your First AI Coding Skill: A Complete Guide

skills-hub.ai team3 min read
tutorialcreate claude code skillbuild ai coding skillSKILL.mdpublishinggetting started

AI coding skills are structured instructions that make your AI assistant an expert in specific frameworks, libraries, and workflows. Building your own skill is surprisingly simple — it is just a SKILL.md file with frontmatter metadata and Markdown instructions. This guide walks you through creating, testing, and publishing your first skill on skills-hub.ai.

What is a SKILL.md file?

A SKILL.md file is the open standard for AI coding skills. It combines YAML frontmatter (metadata like name, description, category, and version) with Markdown content (the actual instructions your AI assistant follows). Think of it as a README that your AI reads and internalizes.

The format is intentionally simple. Only two fields are required: name and description. Everything else is optional but recommended for discoverability and quality scoring.

Step 1: Create the frontmatter

Start by creating a file called SKILL.md in your project. The frontmatter goes at the top between triple-dash fences. Here is a complete example:

---
name: React Query Best Practices
description: >
  Teaches your AI assistant TanStack React Query patterns
  including query keys, cache invalidation, optimistic
  updates, and infinite scroll implementation.
version: 1.0.0
category: Build
tags:
  - react
  - tanstack
  - data-fetching
  - caching
---

The available frontmatter fields are:

  • name (required) — A clear, descriptive name for your skill.
  • description (required) — What the skill teaches. Be specific about frameworks and patterns covered.
  • version — Semantic version (e.g., 1.0.0). Bumped automatically on updates.
  • category — One of the 23 categories like Build, Test, Deploy, Security, or Docs.
  • tags — Array of keywords for search and filtering.

Step 2: Write the instructions

Below the frontmatter, write the actual skill content in Markdown. This is what your AI assistant reads and follows. The best skills are specific, opinionated, and example-driven. Here is an example:

---
name: React Query Best Practices
description: >
  Teaches your AI assistant TanStack React Query patterns.
version: 1.0.0
category: Build
tags:
  - react
  - tanstack
---

# React Query Best Practices

## Query Key Conventions

Always use array keys with a domain prefix:

```typescript
// Good — structured, predictable keys
const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  detail: (id: string) => [...userKeys.all, id] as const,
};
```

## Mutation Patterns

Use optimistic updates for responsive UIs:

```typescript
useMutation({
  mutationFn: updateUser,
  onMutate: async (newData) => {
    await queryClient.cancelQueries({ queryKey: userKeys.detail(id) });
    const previous = queryClient.getQueryData(userKeys.detail(id));
    queryClient.setQueryData(userKeys.detail(id), newData);
    return { previous };
  },
  onError: (_err, _new, context) => {
    queryClient.setQueryData(userKeys.detail(id), context?.previous);
  },
  onSettled: () => {
    queryClient.invalidateQueries({ queryKey: userKeys.detail(id) });
  },
});
```

## Rules

- Never use string-only query keys
- Always invalidate related queries after mutations
- Use staleTime to reduce unnecessary refetches
- Prefer useInfiniteQuery for paginated lists

Tips for writing great instructions

  • Be specific. Instead of "use good patterns," show the exact code pattern you want the AI to follow.
  • Include code examples. AI assistants learn best from concrete examples. Show the right way and optionally the wrong way.
  • Add a Rules section. Bullet-pointed rules at the end give the AI clear constraints to follow.
  • Keep it focused. One skill should cover one domain. A React Query skill should not also cover CSS patterns.
  • Use headings for structure. H2 and H3 headings help the AI parse and reference different sections.

Step 3: Test locally

Before publishing, test your skill locally to make sure it works. Place the SKILL.md file in the correct directory for your AI tool:

# Claude Code
cp SKILL.md .claude/skills/react-query.md

# Cursor
cp SKILL.md .cursor/rules/react-query.mdc

# Windsurf
cp SKILL.md .windsurf/rules/react-query.md

Start a new AI session and ask questions about the topic your skill covers. The AI should respond with the specific patterns and conventions from your skill, not generic advice. If it does not, refine your instructions until the behavior matches your expectations.

Step 4: Publish to skills-hub.ai

Once your skill works locally, publish it to skills-hub.ai so others can discover and install it. You have two options:

Option A: Publish via the web

Visit the publish page on skills-hub.ai. Sign in with GitHub, paste your SKILL.md content, and submit. The platform validates the frontmatter, scores the skill for quality, and makes it immediately available in the catalog.

Option B: Publish via the CLI

Use the skills-hub CLI to publish directly from your terminal:

# Authenticate first
npx @skills-hub-ai/cli auth login

# Publish your skill
npx @skills-hub-ai/cli publish ./SKILL.md

Step 5: Iterate based on feedback

After publishing, your skill gets a quality score based on instruction clarity, code example coverage, and metadata completeness. Check your skill page for the score and community feedback. Update your skill by publishing a new version — the platform automatically bumps the patch version when instructions change.

Example: A complete SKILL.md

Here is a minimal but complete skill file you can use as a starting template:

---
name: Error Handling Patterns
description: >
  Consistent error handling for TypeScript APIs — custom error
  classes, Result types, and centralized error middleware.
version: 1.0.0
category: Build
tags:
  - typescript
  - error-handling
  - api
---

# Error Handling Patterns

## Custom Error Classes

Always extend a base AppError class:

```typescript
class AppError extends Error {
  constructor(
    message: string,
    public statusCode: number = 500,
    public code: string = 'INTERNAL_ERROR',
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}

class NotFoundError extends AppError {
  constructor(resource: string) {
    super(`${resource} not found`, 404, 'NOT_FOUND');
  }
}
```

## Rules

- Never throw plain Error — use AppError subclasses
- Always include a machine-readable error code
- Never leak internal error details to API responses
- Log the full error server-side, return sanitized version to client

Next steps

Ready to build your first skill? Head to the publish page to get started, or read the getting started guide for a deeper dive into the platform. Browse the full catalog of 2,400+ skills for inspiration — every great skill starts by solving a problem you have encountered yourself.