NarraNexus · Skills & Tools

Create a Skill

Write a SKILL.md, host it anywhere, and NarraNexus agents can learn it. No code required — just clear instructions.

What Makes a Skill

A skill is a directory containing at minimum a SKILL.md file. This file is the entire skill — it tells the agent what the skill does, what credentials it needs, and how to use it. The agent reads this file, follows the instructions, and internalizes the capability.

SKILL.mdRequired

The skill manifest and documentation. YAML frontmatter for metadata, Markdown body for instructions.

.skill_meta.json

Auto-generated by the system. Tracks installation source, study status, and credential configuration.

.skill_config.json

Auto-generated. Stores saved credentials and environment variables (base64-encoded).

Supporting files

Scripts, templates, examples, or data files the skill needs. Referenced from SKILL.md.

SKILL.md Format

The frontmatter provides metadata for discovery and dependency checking. The body contains the actual instructions the agent will read and follow.

---
name: "my-skill"
description: "What this skill does in one sentence"
version: "1.0.0"
author: "Your Name"
metadata:
  clawdbot:
    requires:
      env: ["API_KEY", "API_SECRET"]
      bins: ["python", "curl"]
---

# My Skill

## What It Does
Describe the capability this skill provides...

## Setup
1. Go to https://example.com and create an account
2. Generate an API key from the settings page
3. Save the key (the agent will store it automatically)

## Usage
Explain how to use the skill in conversation...

## API Reference
Document the endpoints or commands the agent will use...

Frontmatter Fields

nameUnique identifier for the skill (used as directory name)

descriptionOne-line description shown in skill listings

versionSemantic version for update detection

authorCreator name or organization

requires.envList of environment variable names the skill needs (e.g., API_KEY)

requires.binsList of binary dependencies (e.g., python, curl, node)

Writing Good Instructions

The agent is reading your SKILL.md as-is. The quality of the skill depends entirely on how clearly you write the instructions:

Be explicit about setup steps

Don’t assume the agent knows how to register on your platform. Walk through every step: URL to visit, fields to fill, where to find the API key.

Specify credential names

Use consistent environment variable names (API_KEY, not api-key or apiKey). Declare them in the frontmatter requires.env so the system can track them.

Include error handling

Document common errors and what to do. If an API returns 401, tell the agent to check if the key is expired.

Document recurring tasks

If the skill needs periodic work (e.g., check for updates daily), include a HEARTBEAT.md or describe the schedule clearly. The agent will use job_create to set it up.

Test with a fresh agent

Before publishing, have a new agent study your skill from scratch. Watch for ambiguity, missing steps, or assumptions about prior knowledge.

Hosting & Publishing

Skills can be hosted anywhere accessible via a public URL:

Your websiteHost SKILL.md at any URL. Users tell their agent: "Learn the skill at https://yoursite.com/skill.md"

GitHubPush to a public repo with SKILL.md in the root. Agents can clone it directly.

ClawHubPublish to the community marketplace for wider discovery. Users install by slug via the clawhub CLI.

For what happens when an agent studies your skill, see Learn a Skill.