How to Build an AI Agent Skill: Beginner's Complete Guide

When I built my first MCP skill — a simple unit converter — I was surprised how little code it actually took. The MCP SDK handles all the protocol plumbing; you just write the tool logic. Here's the step-by-step guide I wish I'd had.

What You'll Build

A temperature converter skill: two tools, celsius_to_fahrenheit and fahrenheit_to_celsius. Simple enough to understand quickly, complete enough to be a real template for anything more complex.

What You'll Need

• Node.js v18+ — check with node --version
• An npm account for publishing
• A GitHub account for the TrustedSkills submission
• A code editor — VS Code is ideal

Step 1: Project Setup

mkdir temperature-converter-mcp
cd temperature-converter-mcp
npm init -y
npm install @modelcontextprotocol/sdk

Step 2: Write the Server

Create index.js — this is your entire skill:

#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';

const server = new Server(
  { name: 'temperature-converter', version: '1.0.0' },
  { capabilities: { tools: {} } }
);

// Tell Claude what tools you have
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'celsius_to_fahrenheit',
      description: 'Convert a temperature from Celsius to Fahrenheit',
      inputSchema: {
        type: 'object',
        properties: {
          celsius: { type: 'number', description: 'Temperature in Celsius' }
        },
        required: ['celsius']
      }
    },
    {
      name: 'fahrenheit_to_celsius',
      description: 'Convert a temperature from Fahrenheit to Celsius',
      inputSchema: {
        type: 'object',
        properties: {
          fahrenheit: { type: 'number', description: 'Temperature in Fahrenheit' }
        },
        required: ['fahrenheit']
      }
    }
  ]
}));

// Handle the actual tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === 'celsius_to_fahrenheit') {
    const f = (args.celsius * 9/5) + 32;
    return {
      content: [{ type: 'text', text: `${args.celsius}°C = ${f.toFixed(1)}°F` }]
    };
  }

  if (name === 'fahrenheit_to_celsius') {
    const c = (args.fahrenheit - 32) * 5/9;
    return {
      content: [{ type: 'text', text: `${args.fahrenheit}°F = ${c.toFixed(1)}°C` }]
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

Update package.json:

{
  "name": "@yourusername/temperature-converter-mcp",
  "version": "1.0.0",
  "type": "module",
  "bin": { "temperature-converter-mcp": "./index.js" }
}

chmod +x index.js   # Mac/Linux only

Step 3: Create SKILL.md

This is what TrustedSkills reads. Don't skip it.

---
name: temperature-converter
description: Convert temperatures between Celsius and Fahrenheit
version: 1.0.0
platforms: [mcp, openclaw, claude, cursor]
tags: [utility, temperature]
metadata:
  npm: "@yourusername/temperature-converter-mcp"
  tools: [celsius_to_fahrenheit, fahrenheit_to_celsius]
---

Step 4: Test Locally First

Don't publish until you've tested. Add a local path config:

{
  "mcpServers": {
    "temp-converter": {
      "command": "node",
      "args": ["/absolute/path/to/temperature-converter-mcp/index.js"]
    }
  }
}

Restart Claude Desktop and ask: "What's 100 Celsius in Fahrenheit?" — you should get "100°C = 212.0°F".

Step 5: Publish to npm

npm login
npm publish --access public   # --access public for scoped packages

Test the published version:

npx -y @yourusername/temperature-converter-mcp

Step 6: Submit to TrustedSkills

1. Fork the registry repo
2. Create skills/temperature-converter/SKILL.md
3. Open a Pull Request
4. Review, merge — your skill appears on the site within minutes

SKILL.md Fields

Frequently Asked Questions

Do I need TypeScript to build a skill?

No. JavaScript works perfectly, as shown in this guide. TypeScript adds type safety but isn't required. The MCP SDK supports both equally.

Can I build skills in Python?

Yes. The mcp package on PyPI provides the same SDK in Python. Concepts are identical — you just write Python instead of JavaScript.

How do I add API keys to my skill?

Read them from process.env: const apiKey = process.env.MY_API_KEY. Document required env vars in SKILL.md. Users add them to the "env" block in their MCP config.

How long until a submitted skill appears on TrustedSkills?

Minutes after the PR is merged. Community verification takes days (depends on reviewer availability). Formal Verified status takes weeks — it's a proper security review.