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

A basic MCP server takes very little code. The MCP SDK handles the protocol, so you only write the tool logic. This guide builds a simple temperature converter step by step.

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. Keep the dependencies block that npm install added, or the published package won't start:

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

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

Follow the submission guide. The quickest route: put the skill in a public GitHub repository with a SKILL.md at its root, and add the openclaw-skill topic to the repository. Auto-discovery picks it up on the next scraper run, usually within six hours.

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?

If your repository has the openclaw-skill topic, usually within six hours. Nobody reviews the code by hand. Badges come from provenance (Official, Pinned), an editorial pick (Featured) or an automated scan (Checked). See what each badge means.