中文 | English

aelf Skills

A single discovery and bootstrap entry for the aelf skill ecosystem.

This repository provides:

• Bilingual entry docs for humans and AI agents.
• A machine-readable catalog: skills-catalog.json.
• One-click bootstrap: bootstrap.sh.

AI Quick Prompt (OpenClaw / Codex / Cursor / Claude Code)

Repository: https://github.com/AElfProject/aelf-skills
This is a client-agnostic prompt for OpenClaw, Codex, Cursor, and Claude Code.
Read first: skills-catalog.json, docs/SKILLROUTINGMATRIX.md, docs/AIE2ESCENARIOS.md.
Then run:
1) ./bootstrap.sh --source github --dest ./downloaded-skills
2) bun run health:check -- --skills-root ./downloaded-skills
3) read clientInstall.openclaw / clientInstall.ironclaw from skills-catalog.json; if installCommand exists, execute it locally instead of treating a GitHub tree URL as the final install input
Routing rule: follow SKILLROUTINGMATRIX; if ambiguous, output Recommended/Alternative/Reason.
Failure rule: use Common Recovery Template in docs/AIE2ESCENARIOS.md.

Scope

This hub focuses on discovery, download, install, and capability indexing.

It does not replace each skill repository's own client integration logic. Client-specific setup (OpenClaw, Cursor, Claude Desktop, IronClaw, Codex, Claude Code) remains inside each skill repo. AI agents: jump to AI Navigation for routing and execution guides.

Discovery vs Activation

Treat skill distribution in two stages:

• discovery: GitHub repo URL / npm package / ClawHub slug help the host find the skill.
• activation: the host or agent executes the machine-readable install contract from skills-catalog.json.

• GitHub tree/repo URLs are discovery sources only. Do not treat them as the final IronClaw install artifact.
• For IronClaw, prefer clientInstall.ironclaw.installCommand and expect a trusted local install step.
• For OpenClaw, prefer ClawHub / managed install when distributionSources.clawhubId exists; otherwise use clientInstall.openclaw.installCommand.

Prerequisites

• bun >= 1.1.0 (hard requirement)
• npm >= 10
• git >= 2.39
• tar (GNU tar / bsdtar)

Local Environment Setup

workspace.json paths use ${SKILLS_BASE} placeholders for portability. workspace.json is Codex-local workspace config; external consumers should use skills-catalog.json as the data source.

export SKILLS_BASE=/path/to/your/workspace

Example:

• ${SKILLS_BASE}/AElf/aelf-node-skill
• ${SKILLS_BASE}/awaken/awaken-agent-skills

Install

npm install @blockchain-forever/aelf-skills
or
bun add @blockchain-forever/aelf-skills

Quick Start

# 1) Generate public catalog and sync README tables
bun run catalog:generate
2) Generate local catalog with sourcePath (for local bootstrap/health)
bun run catalog:generate:local
3) Run baseline gates
bun run health:check
bun run readme:check
bun run security:audit
4) Bootstrap selected skills
./bootstrap.sh --only aelf-node-skill --skip-install
5) Check hub/catalog update drift (non-blocking)
bun run update:check

Bootstrap CLI

./bootstrap.sh [--catalog <path>] [--dest <dir>] [--source auto|npm|github|local] [--skip-install] [--skip-health] [--only <csv>]

Defaults:

• --source auto (npm first, fallback to github)
• install enabled
• health check enabled
• skills-catalog.json as catalog source

Update Self-Check

aelf-skills includes built-in update reminders for bootstrap, health:check, and catalog:generate. Checks are non-blocking and cache-backed (default TTL 24h). Reminder output is throttled to once per TTL window by lastNotifiedAt.

Commands:

• bun run update:check
• bun run update:check -- --force
• bun run update:check:json

• AELFSKILLSUPDATE_CHECK=0|1 (default 1)
• AELFSKILLSUPDATETTLHOURS=24 (default 24)
• AELFSKILLSUPDATECACHEPATH=<path> (default ~/.aelf-skills/update-check-cache.json)

Generated Catalog

skills-catalog.json is the stable machine interface.

Main fields per skill:

• id, displayName
• npm (name, version)
• repository.https
• distributionSources (githubRepo, npmPackage, optional clawhubId)
• description, capabilities
• artifacts (skillMd, mcpServer, openclaw)
• setupCommands (compatibility display commands such as claudeDesktop, cursor, openclaw, ironclaw)
• clientSupport (support matrix such as claude_desktop, cursor, ironclaw, codex)
• clientInstall (machine-executable activation contract for openclaw / ironclaw)
• dependsOn (optional, schema 1.3.0)

• docs/schemas/workspace.schema.json
• docs/schemas/skill-frontmatter.schema.json
• docs/schemas/openclaw.schema.json
• docs/schemas/skills-catalog.schema.json

• patch (1.3.x): wording/docs fixes, no field semantics change.
• minor (1.x.0): backward-compatible field additions.
• major (x.0.0): breaking changes only.

AI Navigation

• Catalog field semantics: docs/CATALOGSCHEMA.md | docs/CATALOGSCHEMA.zh-CN.md
• Intent routing matrix: docs/SKILLROUTINGMATRIX.md | docs/SKILLROUTINGMATRIX.zh-CN.md
• End-to-end execution scenarios (with recovery): docs/AIE2ESCENARIOS.md | docs/AIE2ESCENARIOS.zh-CN.md
• Type safety baseline and rollout status: docs/TYPESAFETYMATRIX.md | docs/TYPESAFETYMATRIX.zh-CN.md

# Check local source repositories from workspace.json
bun run health:check
Check downloaded skills under specific root
bun run health:check -- --skills-root ./downloaded-skills

• Contribution guide: CONTRIBUTING.zh-CN.md | CONTRIBUTING.md
• AI execution contract: docs/AISKILLCONTRACT.zh-CN.md | docs/AISKILLCONTRACT.md
• AI prompt template: docs/templates/AINEWSKILLPROMPT.zh-CN.md | docs/templates/AINEWSKILLPROMPT.md
• PR checklist: docs/templates/NEWSKILLCHECKLIST.zh-CN.md | docs/templates/NEWSKILLCHECKLIST.md
• Skill markdown template: docs/templates/SKILLTEMPLATE.zh-CN.md | docs/templates/SKILLTEMPLATE.md
• Golden path example: docs/examples/EXAMPLENEWSKILLDIFF.zh-CN.md | docs/examples/EXAMPLENEWSKILLDIFF.md