feat(skills): gaia skill migrate — OpenClaw/Hermes skills to GAIA format

[kovtcharov]

Skill authors on OpenClaw/ClawHub and Hermes had no path onto GAIA short of rewriting each SKILL.md by hand, which meant GAIA's catalog started empty while a large body of compatible skills sat one format away. gaia skill migrate --from openclaw|hermes|auto reads the foreign metadata.<vendor> namespace and writes a metadata.gaia block, so an existing library moves over largely untouched — point it at one skill or a whole ClawHub checkout. Every migrated skill lands at the experimental tier via the same trust reset gaia skill import uses, and a skill that needs a local capability GAIA cannot yet enforce is refused with the reason rather than quietly stripped of the permission to make the migration look like it worked.

Validated against 26 real published ClawHub skills (commit-pinned, licenses and digests recorded in tests/fixtures/openclaw_skills/PROVENANCE.md): 13 migrate cleanly, 13 are correctly refused — 10 because they shell out, 3 because they ship no frontmatter at all.

The dashboard half of #692 is deferred to #701, deliberately. There is no skills surface in the Agent UI today — no /api/skills router, no panel, not even the word "skill" anywhere in src/gaia/ui/ — and no in-flight branch adding one. Building visual import here would mean building Phase 3's surface to hang it off, and a user would import a skill into a UI that cannot list it. The migrator is UI-ready instead: MigrationOutcome.to_dict() is JSON-serializable and --json emits the full report, so the panel wires to gaia.skills.migrate rather than reimplementing the mapping. The plan doc's Phase 3 section now records that.

Two bugs surfaced only by the real corpus, both silent-loss paths that a docs-driven implementation would have shipped:

• A skill putting its OpenClaw fields directly under metadata (or at the top level, with no namespace key) migrated with zero permissions — so 1password shelling out to op was refused when namespaced and silently accepted when not. Same upstream skill, opposite verdicts, the unsafe one passing.
• metadata.openclaw: "a string" had its value dropped while the report claimed the namespace was "absent or empty".

Stacked on #2669 (Phase 1) — base retargets to main when that merges.

Closes #692

Test plan

• python -m pytest tests/unit/test_skills_migrate.py -q — 64 tests: round-trip through parse_skill_file, vendor fields surviving under metadata.<vendor>, experimental stamped over a claimed verified/community, local-capability sources reported unmigratable rather than downgraded, and the Hermes path through the same command.
• python -m pytest tests/unit/test_skills_format.py tests/unit/test_skills_cli.py -q — Phase 1 unaffected by the shared reset_security_tier() / split_frontmatter() extraction.
• Every one of the 26 real fixtures is asserted to reach a defined verdict (parametrized), and two guard tests keep the corpus honest: ≥10 real skills present with provenance, and both verdicts still exercised.
• Cold-state CLI run — nothing touches a real ~/.gaia/skills:

  export GAIA_CONFIG_DIR=$(mktemp -d)
  gaia skill migrate tests/fixtures/openclaw_skills --from openclaw --dry-run
  gaia skill migrate tests/fixtures/openclaw_skills --from openclaw   # exit 4: 13 refused
  gaia skill info linear                                              # security tier: experimental

• python util/lint.py --all

The base branch was changed.

[github-actions]

Verdict: Request changes

This PR adds gaia skill migrate to convert OpenClaw/Hermes skills into GAIA format, with a solid real-corpus fixture set (26 published skills) and thorough tests. Nice work overall.

The one blocking issue: the documented flagship command aborts the whole batch on real input. Running gaia skill migrate ~/clawhub-skills --dry-run (default --from auto, exactly the "whole collection" example in the CLI docs) crashes out at the first skill that has no vendor namespace — none of the other skills in the directory are migrated or even reported. A real ClawHub collection routinely contains plain Agent-Skills documents, so this fires on the primary use case. The fix: one un-detectable skill in a collection should be reported as a per-skill blocker and the batch should continue — which is exactly what this PR already does for the no-frontmatter case (and even tests). The no-vendor-namespace case just wasn't given the same treatment at the batch layer.

Real-world evidence

The evidence bundle (evidence-bundle.md, CLI-only surface — API/MCP correctly N/A) exercised the real gaia skill migrate CLI and reproduced the bug above against this PR's own fixture corpus:

$ gaia skill migrate tests/fixtures/openclaw_skills --dry-run
❌ tests/fixtures/openclaw_skills/anki-connect/SKILL.md: no vendor namespace found, so there is nothing to migrate. ...
$ echo $?   # 4 — that is the ENTIRE output; the other 25 skills are never processed

Forcing --from openclaw (bypassing auto-detect) instead produces the full 26-skill per-skill report (13/26 migrated), confirming the abort is specific to vendor="auto" hitting a no-vendor skill. Real fixtures that trigger it: anki-connect, clawhip, gui-agent-harness. The bundle also verified the happy paths (single migrate + install, --force collision, --json, Hermes auto-detect, error paths), 264 unit tests passing, lint clean, and a spot-regression pass over sibling gaia skill subcommands. My verdict rests on that evidence plus static review of the two code paths below.

🔍 Technical details

🔴 migrate aborts the whole batch when auto-detect fails on any skill (src/gaia/skills/cli.py:432)

_handle_migrate builds outcomes in a bare list comprehension with no per-item guard:

outcomes = [
    migrate_skill_dir(source, vendor=args.vendor, name=args.name)
    for source in sources
]

For vendor="auto" (the default), migrate_text (src/gaia/skills/migrate.py:617-627) raises SkillValidationError when detect_vendor() returns None. That raise propagates out of the comprehension, through handle()'s single outer except SkillValidationError (cli.py:213), and aborts the entire run — so a collection where one member is a plain Agent-Skills doc reports nothing for the other members.

This contradicts the PR's own batch-resilience design: the no-frontmatter case is caught inside migrate_text and returned as a per-skill blocker (migrate.py:605-615), locked in by test_missing_frontmatter_is_a_blocker_not_a_crash ("one must not abort a batch"). The no-vendor-namespace case deserves the same treatment.

Note the single-skill raise semantics are intentional and tested at the library level (test_auto_detect_refuses_a_plain_agent_skills_document calls migrate_skill_dir directly), so the cleanest fix is at the batch/CLI layer — guard each item and convert the raise to a blocker outcome:

    outcomes = []
    for source in sources:
        try:
            outcomes.append(
                migrate_skill_dir(source, vendor=args.vendor, name=args.name)
            )
        except SkillValidationError as exc:
            # One un-detectable skill in a collection must not abort the batch —
            # report it as a per-skill blocker, like the no-frontmatter case.
            outcomes.append(
                MigrationOutcome(source=Path(source), vendor="unknown", blockers=[str(exc)])
            )

This needs MigrationOutcome added to the from gaia.skills.migrate import (...) block at cli.py:34. Please also add a CLI-level regression test: a directory where one skill has a vendor namespace and one is a plain doc, run with default vendor="auto", and assert the batch still reports both (the existing test_cli_migrate_reports_a_collision_without_hiding_the_batch doesn't cover this because both its fixtures carry a vendor block).

Strengths

• Batch resilience is a first-class concern elsewhere — the no-frontmatter and install-collision paths are both handled as per-skill outcomes with dedicated tests and clear user messaging.
• Migration is validated against 26 real published skills as fixtures, not just synthetic inputs, and refused skills fail loudly with actionable reasons rather than silently stripping permissions.
• Clean separation: migrate_text (pure) vs migrate_skill_dir/install_migrated (I/O), --json output for scripting, and consistent exit codes.