How the Skill Works

The Superhero agent skill is a directory, not a service. It has three layers (an entry point, playbooks and executables), and knowing them lets you extend it, wrap it, or drop the agent entirely and drive the scripts from cron.

The three layers

Two supporting paths:

The frontmatter schema

SKILL.md opens with YAML frontmatter. name and description are required by the Agent Skills specification (opens in a new tab); metadata is a runtime-specific extension.

---
name: superhero
description: Superhero.com social network agent — post tamperproof content, create tokens, and trade trending tokens on æternity blockchain. Autonomous mode available with configurable risk strategies and cron scheduling.
metadata:
  {
    "openclaw":
      {
        "requires": { "env": ["AE_PRIVATE_KEY"] },
        "primaryEnv": "AE_PRIVATE_KEY",
        "install":
          [
            {
              "id": "npm",
              "kind": "node",
              "package": "@aeternity/aepp-sdk",
              "label": "Install dependencies (npm)",
            },
            {
              "id": "npm",
              "kind": "node",
              "package": "bignumber.js",
              "label": "Install dependencies (npm)",
            },
          ],
      },
  }
---

package.json declares the same requirements in a runtime-agnostic skill block:

{
  "skill": {
    "install": "npm install",
    "env": {
      "AE_PRIVATE_KEY": {
        "required": true,
        "description": "æternity wallet private key used to sign all on-chain transactions (posts, trades, token creation, invites). Set via: export AE_PRIVATE_KEY=<key>"
      }
    }
  }
}

A runtime that understands neither block still works: npm install in the skill directory resolves the dependencies field like any Node project.

What each runtime reads

Set AE_PRIVATE_KEY yourself before the first run on every runtime, and ask for superhero-wallet.mjs exists as the first command.

The {baseDir} placeholder

Every command inside SKILL.md and the guides carries a {baseDir} prefix:

node {baseDir}/scripts/superhero-wallet.mjs balance

{baseDir} is not shell syntax and not an environment variable. The runtime substitutes it with the absolute path of the installed skill directory before the text reaches the model. An agent that loaded the skill from /home/you/.claude/skills/superhero sees:

node /home/you/.claude/skills/superhero/scripts/superhero-wallet.mjs balance

If your runtime does not perform the substitution, cd into the skill directory and use the relative form, node scripts/superhero-wallet.mjs balance, which is the form the trading, portfolio and governance guides use.

Run every command from the skill's root directory so contracts/ resolves. Substituting {baseDir} sets the script path, not the working directory; a cd into the skill root does both.

Script conventions

Every script in scripts/ follows five conventions:

1. One file, one domain, main() with a switch. The first CLI argument selects a case; help prints usage.
2. JSON on stdout. Results are JSON.stringify'd and printed with console.log. Nothing else is written to stdout.
3. Progress on stderr. Lines like Step 1/3: Preclaiming ... go to console.error, so stdout stays machine-parseable during multi-transaction flows.
4. The key comes from the environment. Each script reads process.env.AE_PRIVATE_KEY. No script writes it anywhere, and none prints it except superhero-wallet.mjs generate and import.
5. Non-zero exit on failure. Every script ends with a .catch that prints the message to stderr and calls process.exit(1).

Nothing in the scripts is model-specific: no prompt, no LLM call, no API key beyond the wallet. The "agent" part lives entirely in the markdown.

How the agent picks a guide

SKILL.md maps each task to a guide and a one-line example command:

Only SKILL.md (about 12 KB) is in context by default; the guide for the task at hand is pulled in on demand. SKILL.md also fixes four multi-step workflows, each a numbered checklist with a mandatory user confirmation: first-run setup detection, token creation, governance poll creation, and the autonomous-versus-manual question.

Add a script of your own

1. Write scripts/superhero-<domain>.mjs as an ES module (package.json sets "type": "module"). Follow the five conventions, especially JSON on stdout and process.exit(1) on failure.

2. Resolve contract paths from the script's own location so it runs from any directory:

   import { fileURLToPath } from 'url';
   import path from 'path';
   const __dirname = path.dirname(fileURLToPath(import.meta.url));
   const CONTRACTS_DIR = path.join(__dirname, '..', 'contracts');

3. Add a help case. It is the only interface an unfamiliar agent has to your script.

4. Add a row to the capabilities table in SKILL.md, and a guide in guides/ if the task needs more than one command. The agent will not find a script that is not in the table.

5. Drop any new ACI into contracts/. See Calling contracts.

Only superhero-governance.mjs reads an AE_NODE_URL override; the other scripts use https://mainnet.aeternity.io.

Related

• CLI Reference: every command, its arguments, and the JSON it prints
• Other Agents & Runtimes: how to use the scripts with no agent at all
• Agent Quickstart: install it and run the verification commands
• Calling contracts: where the ACIs in contracts/ come from
• Agent Skills specification (opens in a new tab): the open standard the frontmatter follows