Skip to content

AElfProject/aelf-skills

aelf-skills-hub

Verified

Discovery, download, and configuration hub for the entire aelf agent skill ecosystem. Use when the user wants to: (1) explore or list available aelf skills, (2) install/bootstrap aelf skills into Cursor, Claude Desktop, OpenClaw, Codex, or Claude Code, (3) route an aelf-related intent to the correct skill, (4) check health or audit installed skills, (5) onboard a new skill into the aelf ecosystem. Covers domains: Portkey CA wallet, Portkey EOA wallet, Awaken DEX, eForest NFT marketplace, AelfScan explorer, TomorrowDAO governance, aelf node interaction.

scripts/lib/catalog.ts

View on GitHub
import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import path from 'node:path';
import {
  expandPathWithEnv,
  extractFirstHeading,
  extractSectionBullets,
  normalizeRepoUrlToHttps,
  parseFrontMatter,
  readJsonFile,
  replaceSection,
  runCommand,
  slugifyId,
  writeJsonFile,
} from './utils.ts';
import type {
  SkillCatalogEntry,
  SkillClientInstall,
  SkillClientInstallEntry,
  SkillsCatalog,
  WorkspaceConfig,
  WorkspaceProject,
} from './types.ts';

const SKILL_TABLE_START = '<!-- SKILL_TABLE_START -->';
const SKILL_TABLE_END = '<!-- SKILL_TABLE_END -->';
const REPOSITORY_HTTPS_OVERRIDES: Record<string, string> = {
  '@tomorrowdao/agent-skills': 'https://github.com/TomorrowDAOProject/tomorrowDAO-skill.git',
};
const DESCRIPTION_ZH_OVERRIDES: Record<string, string> = {
  '@blockchain-forever/aelf-node-skill': 'AElf 节点查询与合约调用技能。',
  '@aelfscan/agent-skills': 'AelfScan 浏览器数据检索与分析技能。',
  '@awaken-finance/agent-kit': 'Awaken DEX 交易与行情数据技能。',
  '@eforest-finance/agent-skills': 'eForest 代币与 NFT 市场操作技能。',
  '@portkey/ca-agent-skills': 'Portkey CA 钱包注册、认证、Guardian 与转账技能。',
  '@portkey/eoa-agent-skills': 'Portkey EOA 钱包与资产操作技能。',
  '@tomorrowdao/agent-skills': 'TomorrowDAO 治理、BP 与资源操作技能。',
};
const CLAWHUB_ID_OVERRIDES: Record<string, string> = {};

interface BuiltSkillCandidate {
  entry: SkillCatalogEntry;
  projectPath: string;
  declaredDependsOn: string[];
}

export interface BuildCatalogOptions {
  workspacePath?: string;
  includeLocalPaths?: boolean;
}

export interface WriteCatalogArtifactsOptions {
  rootDir?: string;
  outputPath?: string;
  syncReadme?: boolean;
}

interface PackageJsonLike {
  name?: string;
  version?: string;
  description?: string;
  scripts?: Record<string, string>;
  bin?: string | Record<string, string>;
  repository?: string | { type?: string; url?: string };
}

export function buildCatalog(options: BuildCatalogOptions = {}): SkillsCatalog {
  const workspacePath = path.resolve(options.workspacePath || path.join(process.cwd(), 'workspace.json'));
  const workspaceDir = path.dirname(workspacePath);
  const workspace = readJsonFile<WorkspaceConfig>(workspacePath);
  const includeLocalPaths = options.includeLocalPaths === true;

  const warnings: string[] = [];
  const candidates: BuiltSkillCandidate[] = [];

  for (const project of workspace.projects) {
    const projectPath = resolveProjectPath(project, workspaceDir);
    const packagePath = path.join(projectPath, 'package.json');
    const skillPath = path.join(projectPath, 'SKILL.md');

    if (!existsSync(packagePath)) {
      pushWarning(warnings, 'SKIP', projectPath, includeLocalPaths, 'package.json not found');
      continue;
    }

    if (!existsSync(skillPath)) {
      pushWarning(warnings, 'WARN', projectPath, includeLocalPaths, 'SKILL.md not found, project skipped');
      continue;
    }

    const entry = buildSkillEntry(projectPath, warnings, includeLocalPaths);
    if (!entry) {
      continue;
    }

    candidates.push({
      entry,
      projectPath,
      declaredDependsOn: normalizeDependsOn(project.dependsOn),
    });
  }

  validateDuplicateIds(candidates);
  const skills = applyAndValidateDependencies(candidates);

  skills.sort((a, b) => a.id.localeCompare(b.id));

  return {
    schemaVersion: '1.3.0',
    generatedAt: new Date().toISOString(),
    source: path.basename(workspacePath),
    skills,
    warnings,
  };
}

export function writeCatalogArtifacts(catalog: SkillsCatalog, options: WriteCatalogArtifactsOptions = {}): void {
  const rootDir = options.rootDir || process.cwd();
  const outputPath = options.outputPath
    ? path.resolve(rootDir, options.outputPath)
    : path.join(rootDir, 'skills-catalog.json');

  writeJsonFile(outputPath, catalog);

  if (options.syncReadme === false) {
    return;
  }

  syncReadmeTable(path.join(rootDir, 'README.md'), renderSkillTable(catalog, 'en'));
  syncReadmeTable(path.join(rootDir, 'README.zh-CN.md'), renderSkillTable(catalog, 'zh'));
}

function resolveProjectPath(project: WorkspaceProject, workspaceDir: string): string {
  const expandedPath = expandPathWithEnv(project.path);
  return path.resolve(workspaceDir, expandedPath);
}

function buildSkillEntry(
  projectPath: string,
  warnings: string[],
  includeLocalPaths: boolean,
): SkillCatalogEntry | null {
  const packagePath = path.join(projectPath, 'package.json');
  const skillPath = path.join(projectPath, 'SKILL.md');
  const openclawPath = path.join(projectPath, 'openclaw.json');
  const mcpServerPath = path.join(projectPath, 'src', 'mcp', 'server.ts');

  const pkg = readJsonFile<PackageJsonLike>(packagePath);
  const skillMd = readFileSync(skillPath, 'utf8');
  const frontMatter = parseFrontMatter(skillMd);
  const zhDescription = frontMatter.description_zh || (pkg.name ? DESCRIPTION_ZH_OVERRIDES[pkg.name] : undefined);

  if (!pkg.name || !pkg.version) {
    pushWarning(warnings, 'SKIP', projectPath, includeLocalPaths, 'package name/version missing');
    return null;
  }

  const setupBase = detectSetupBase(pkg, projectPath);
  const setupBin = detectSetupBin(pkg);
  const capabilities = extractSectionBullets(skillMd, 'Capabilities');
  const description = frontMatter.description || pkg.description || `Agent skill package ${pkg.name}`;

  if (!existsSync(openclawPath)) {
    pushWarning(warnings, 'WARN', projectPath, includeLocalPaths, 'openclaw.json not found');
  }

  const openclawToolCount = getOpenclawToolCount(openclawPath, warnings, projectPath, includeLocalPaths);
  const repositoryHttps = resolveRepositoryHttps(pkg, projectPath);
  const clawhubId = resolveClawhubId(pkg.name);
  const hasMcp = existsSync(mcpServerPath) || Boolean(pkg.scripts?.mcp);
  const hasOpenclaw = existsSync(openclawPath);
  const hasCli = Boolean(pkg.scripts?.cli);
  const hasSetup = Boolean(setupBase);

  return {
    id: frontMatter.name ? slugifyId(frontMatter.name) : slugifyId(pkg.name),
    displayName: extractFirstHeading(skillMd) || pkg.name,
    npm: {
      name: pkg.name,
      version: pkg.version,
    },
    repository: {
      ...(repositoryHttps ? { https: repositoryHttps } : {}),
    },
    distributionSources: {
      ...(repositoryHttps ? { githubRepo: repositoryHttps } : {}),
      npmPackage: pkg.name,
      ...(clawhubId ? { clawhubId } : {}),
    },
    description,
    ...(zhDescription ? { description_zh: zhDescription } : {}),
    capabilities,
    artifacts: {
      skillMd: true,
      mcpServer: hasMcp,
      openclaw: hasOpenclaw,
    },
    setupCommands: buildSetupCommands(setupBase),
    clientSupport: buildClientSupport({
      hasMcp,
      hasOpenclaw,
      hasCli,
      hasSetup,
    }),
    clientInstall: buildClientInstall({
      packageName: pkg.name,
      setupBin,
      clawhubId,
      hasOpenclaw,
      hasIronclaw: hasMcp && hasSetup,
    }),
    openclawToolCount,
    ...(includeLocalPaths ? { sourcePath: projectPath } : {}),
  };
}

function validateDuplicateIds(candidates: BuiltSkillCandidate[]): void {
  const idToPaths = new Map<string, string[]>();

  for (const candidate of candidates) {
    const arr = idToPaths.get(candidate.entry.id) || [];
    arr.push(candidate.projectPath);
    idToPaths.set(candidate.entry.id, arr);
  }

  const duplicates = Array.from(idToPaths.entries()).filter(([, paths]) => paths.length > 1);
  if (duplicates.length === 0) {
    return;
  }

  const detail = duplicates
    .map(([id, paths]) => `- ${id}: ${paths.join(' | ')}`)
    .join('\n');
  throw new Error(`[FAIL] Duplicate skill id detected:\n${detail}`);
}

function applyAndValidateDependencies(candidates: BuiltSkillCandidate[]): SkillCatalogEntry[] {
  const knownIds = new Set(candidates.map(candidate => candidate.entry.id));
  const skills: SkillCatalogEntry[] = [];
  const errors: string[] = [];

  for (const candidate of candidates) {
    const { entry, declaredDependsOn } = candidate;
    if (declaredDependsOn.length > 0) {
      const unknown = declaredDependsOn.filter(depId => !knownIds.has(depId));
      if (unknown.length > 0) {
        errors.push(
          `[FAIL] ${entry.id}: dependsOn references unknown skill id(s): ${unknown.join(', ')} (source: ${candidate.projectPath})`,
        );
      } else {
        entry.dependsOn = declaredDependsOn;
      }
    }

    skills.push(entry);
  }

  if (errors.length > 0) {
    throw new Error(errors.join('\n'));
  }

  return skills;
}

function normalizeDependsOn(dependsOn?: string[]): string[] {
  if (!dependsOn || dependsOn.length === 0) {
    return [];
  }

  const seen = new Set<string>();
  const normalized: string[] = [];

  for (const value of dependsOn) {
    const trimmed = value.trim();
    if (!trimmed || seen.has(trimmed)) {
      continue;
    }
    seen.add(trimmed);
    normalized.push(trimmed);
  }

  return normalized;
}

function getOpenclawToolCount(
  openclawPath: string,
  warnings: string[],
  projectPath: string,
  includeLocalPaths: boolean,
): number {
  if (!existsSync(openclawPath)) return 0;
  try {
    const data = readJsonFile<{ tools?: unknown[] }>(openclawPath);
    return Array.isArray(data.tools) ? data.tools.length : 0;
  } catch {
    pushWarning(warnings, 'WARN', projectPath, includeLocalPaths, 'openclaw.json parse failed');
    return 0;
  }
}

function resolveRepositoryHttps(pkg: PackageJsonLike, projectPath: string): string | undefined {
  if (pkg.name && REPOSITORY_HTTPS_OVERRIDES[pkg.name]) {
    return REPOSITORY_HTTPS_OVERRIDES[pkg.name];
  }

  const fromPkg = normalizeRepoUrlToHttps(extractRepositoryFromPackage(pkg));
  if (fromPkg) return canonicalizeRepositoryHttps(fromPkg);

  const gitResult = runCommand('git', ['-C', projectPath, 'remote', 'get-url', 'origin']);
  if (!gitResult.ok || !gitResult.stdout) return undefined;
  const normalized = normalizeRepoUrlToHttps(gitResult.stdout);
  return canonicalizeRepositoryHttps(normalized);
}

function extractRepositoryFromPackage(pkg: PackageJsonLike): string | undefined {
  if (!pkg.repository) return undefined;
  if (typeof pkg.repository === 'string') return pkg.repository;
  return pkg.repository.url;
}

function detectSetupBase(pkg: PackageJsonLike, projectPath: string): string | undefined {
  const hasSetupScript = Boolean(pkg.scripts?.setup);
  if (hasSetupScript) return 'bun run setup';

  const setupTs = path.join(projectPath, 'bin', 'setup.ts');
  const setupJs = path.join(projectPath, 'bin', 'setup.js');
  if (existsSync(setupTs)) return 'bun run bin/setup.ts';
  if (existsSync(setupJs)) return 'bun run bin/setup.js';
  return undefined;
}

function detectSetupBin(pkg: PackageJsonLike): string | undefined {
  if (!pkg.bin) return undefined;

  if (typeof pkg.bin === 'string') {
    return normalizeSetupTarget(pkg.bin) ? defaultBinName(pkg.name) : undefined;
  }

  for (const [binName, target] of Object.entries(pkg.bin)) {
    if (normalizeSetupTarget(target)) {
      return binName;
    }
  }

  return undefined;
}

function defaultBinName(packageName?: string): string | undefined {
  if (!packageName) return undefined;
  const [, unscoped = packageName] = packageName.split('/');
  return unscoped;
}

function normalizeSetupTarget(target: string): boolean {
  const normalized = target.replace(/\\/g, '/').replace(/^\.\//, '');
  return normalized === 'bin/setup.js' || normalized === 'bin/setup.ts';
}

function resolveClawhubId(packageName?: string): string | undefined {
  if (!packageName) return undefined;
  return CLAWHUB_ID_OVERRIDES[packageName];
}

function buildSetupCommands(setupBase?: string) {
  const install = 'bun install';
  if (!setupBase) return { install };

  return {
    install,
    list: `${setupBase} list`,
    openclaw: `${setupBase} openclaw`,
    cursor: `${setupBase} cursor`,
    claudeDesktop: `${setupBase} claude`,
    ironclaw: `${setupBase} ironclaw`,
  };
}

function buildClientSupport(input: {
  hasMcp: boolean;
  hasOpenclaw: boolean;
  hasCli: boolean;
  hasSetup: boolean;
}) {
  const openclaw = input.hasOpenclaw ? (input.hasSetup ? 'native' : 'manual') : 'unsupported';

  const nativeMcp = input.hasMcp && input.hasSetup ? 'native-setup' : 'manual-mcp';

  return {
    openclaw,
    cursor: input.hasMcp ? nativeMcp : 'unsupported',
    claude_desktop: input.hasMcp ? nativeMcp : 'unsupported',
    ironclaw: input.hasMcp ? nativeMcp : 'unsupported',
    claude_code: input.hasMcp ? 'manual-mcp' : 'unsupported',
    codex: input.hasMcp || input.hasCli ? 'manual-cli-or-mcp' : 'unsupported',
  };
}

function buildClientInstall(input: {
  packageName: string;
  setupBin?: string;
  clawhubId?: string;
  hasOpenclaw: boolean;
  hasIronclaw: boolean;
}): SkillClientInstall {
  return {
    openclaw: buildOpenclawInstall(input),
    ironclaw: buildIronclawInstall(input),
  };
}

function buildOpenclawInstall(input: {
  packageName: string;
  setupBin?: string;
  clawhubId?: string;
  hasOpenclaw: boolean;
}): SkillClientInstallEntry {
  if (!input.hasOpenclaw) {
    return { source: 'none', mode: 'unsupported' };
  }

  if (input.clawhubId) {
    return {
      source: 'clawhub',
      mode: 'managed-install',
    };
  }

  if (!input.setupBin) {
    return { source: 'none', mode: 'unsupported' };
  }

  return {
    source: 'npm',
    mode: 'package-setup',
    installCommand: `bunx -p ${input.packageName} ${input.setupBin} openclaw`,
  };
}

function buildIronclawInstall(input: {
  packageName: string;
  setupBin?: string;
  hasIronclaw: boolean;
}): SkillClientInstallEntry {
  if (!input.hasIronclaw || !input.setupBin) {
    return { source: 'none', mode: 'unsupported' };
  }

  return {
    source: 'npm',
    mode: 'trusted-local-install',
    installCommand: `bunx -p ${input.packageName} ${input.setupBin} ironclaw`,
    requiresTrustPromotion: true,
  };
}

function syncReadmeTable(readmePath: string, tableContent: string): void {
  if (!existsSync(readmePath)) return;
  const original = readFileSync(readmePath, 'utf8');
  const updated = replaceSection(original, SKILL_TABLE_START, SKILL_TABLE_END, tableContent);
  if (updated !== original) {
    writeFileSync(readmePath, updated, 'utf8');
  }
}

function renderSkillTable(catalog: SkillsCatalog, locale: 'en' | 'zh'): string {
  const header =
    locale === 'zh'
      ? '| ID | npm 包名 | 版本 | OpenClaw 工具数 | 描述 |'
      : '| ID | npm Package | Version | OpenClaw Tools | Description |';
  const divider = '|---|---|---:|---:|---|';

  const rows = catalog.skills.map(skill => {
    const description = locale === 'zh' ? skill.description_zh || skill.description : skill.description;
    const desc = description.replace(/\|/g, '\\|');
    return `| ${skill.id} | ${skill.npm.name} | ${skill.npm.version} | ${skill.openclawToolCount} | ${desc} |`;
  });

  return [header, divider, ...rows].join('\n');
}

function pushWarning(
  warnings: string[],
  level: 'WARN' | 'SKIP',
  projectPath: string,
  includeLocalPaths: boolean,
  message: string,
): void {
  warnings.push(`[${level}] ${formatWarningTarget(projectPath, includeLocalPaths)}: ${message}`);
}

function formatWarningTarget(projectPath: string, includeLocalPaths: boolean): string {
  if (includeLocalPaths) return projectPath;
  const normalized = projectPath.replace(/\\/g, '/');
  const workspaceMarker = '/workspace/';
  const markerIndex = normalized.indexOf(workspaceMarker);
  if (markerIndex >= 0) {
    return normalized.slice(markerIndex + workspaceMarker.length);
  }

  const segments = normalized.split('/').filter(Boolean);
  if (segments.length >= 2) {
    return `${segments[segments.length - 2]}/${segments[segments.length - 1]}`;
  }
  return path.basename(projectPath);
}

function canonicalizeRepositoryHttps(raw?: string): string | undefined {
  if (!raw) return undefined;

  try {
    const parsed = new URL(raw);
    if (parsed.hostname === 'tmrwdao.github.com') {
      parsed.hostname = 'github.com';
    }
    return parsed.toString();
  } catch {
    return raw;
  }
}
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall