feat(skills): migrate to agentskills.io spec compliance

[whoabuddy]

Summary

• Migrate all 40 SKILL.md files from flat frontmatter to the agentskills.io metadata: nested structure
• Introduce two-tier validation: skills-ref (spec schema) + Zod (repo-level rules)
• Update README.md frontmatter examples to reflect the new format
• Remove one-time migration script after successful migration

What Changed

SKILL.md Format (all 40 files)

Before (flat format):

---
name: btc
description: Bitcoin L1 operations — ...
user-invocable: false
arguments: balance | fees | ...
entry: btc/btc.ts
requires: [wallet]
tags: [l1, write, requires-funds]
---

After (agentskills.io spec):

---
name: btc
description: Bitcoin L1 operations — ...
metadata:
  user-invocable: "false"
  arguments: "balance | fees | ..."
  entry: "btc/btc.ts"
  requires: "wallet"
  tags: "l1, write, requires-funds"
  author: "whoabuddy"
  author-agent: "Trustless Indra"
---

Two-Tier Validation

bun run validate now runs two layers:

1. skills-ref (tier 1) — validates against the official agentskills.io JSON Schema. Catches spec-level violations: missing required fields, wrong nesting, wrong types.
2. Zod (tier 2) — validates repo-level rules: allowed tag values, entry file existence, requires cross-references. These are constraints specific to this repo beyond the base spec.

generate-manifest.ts

Updated to read from the metadata: nested object when building skills.json. The manifest output format is unchanged — consumers see the same flat structure they always did.

Checklist

• All 40 SKILL.md files validated by bun run validate (79 passed, 0 failed)
• bun run typecheck passes with 0 errors
• bun run manifest produces valid skills.json
• README.md frontmatter examples updated
• Migration script removed (one-time tool, no longer needed)

Closes #110

Co-Authored-By: Claude noreply@anthropic.com

[Copilot]

Pull request overview

Migrates the repository’s SKILL.md frontmatter to the agentskills.io metadata: nesting and updates repo tooling/docs to validate and generate skills.json from the new format.

Changes:

• Migrate skill frontmatter from flat keys/bracket-lists to metadata: with quoted, comma-separated strings.
• Add tiered validation (skills-ref + Zod) and switch validation/manifest scripts to real YAML parsing.
• Update documentation examples and add yaml dependency; ignore local .venv-skills-ref/.

Reviewed changes

Copilot reviewed 46 out of 48 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
scripts/validate-frontmatter.ts	Adds skills-ref tier-1 validation, YAML parsing, and updated Zod validation for new metadata: format
scripts/generate-manifest.ts	Switches manifest generation to parse nested metadata: via YAML parser
package.json	Adds yaml dependency used by validation/manifest scripts
bun.lock	Locks the new yaml dependency and updates lock metadata
skills.json	Regenerated manifest (version bump + additional fields emitted)
README.md	Updates SKILL frontmatter documentation to new agentskills.io-compliant format
CLAUDE.md	Updates SKILL frontmatter guidance/table to the new metadata: structure
.gitignore	Ignores local .venv-skills-ref/ used for optional skills-ref installs
agent-lookup/SKILL.md	Migrates frontmatter to metadata: format
aibtc-agents/SKILL.md	Migrates frontmatter to metadata: format
aibtc-news/SKILL.md	Migrates frontmatter to metadata: format
aibtc-news-classifieds/SKILL.md	Migrates frontmatter to metadata: format
aibtc-news-deal-flow/SKILL.md	Migrates frontmatter to metadata: format
aibtc-news-protocol/SKILL.md	Migrates frontmatter to metadata: format
bitflow/SKILL.md	Migrates frontmatter to metadata: format
bns/SKILL.md	Migrates frontmatter to metadata: format
btc/SKILL.md	Migrates frontmatter to metadata: format
business-dev/SKILL.md	Migrates frontmatter to metadata: format
ceo/SKILL.md	Migrates frontmatter to metadata: format
credentials/SKILL.md	Migrates frontmatter to metadata: format
defi/SKILL.md	Migrates frontmatter to metadata: format
dual-stacking/SKILL.md	Migrates frontmatter to metadata: format
identity/SKILL.md	Migrates frontmatter to metadata: format
mempool-watch/SKILL.md	Migrates frontmatter to metadata: format
nft/SKILL.md	Migrates frontmatter to metadata: format
nostr/SKILL.md	Migrates frontmatter to metadata: format
onboarding/SKILL.md	Migrates frontmatter to metadata: format
ordinals/SKILL.md	Migrates frontmatter to metadata: format
ordinals-p2p/SKILL.md	Migrates frontmatter to metadata: format
pillar/SKILL.md	Migrates frontmatter to metadata: format
query/SKILL.md	Migrates frontmatter to metadata: format
reputation/SKILL.md	Migrates frontmatter to metadata: format
sbtc/SKILL.md	Migrates frontmatter to metadata: format
settings/SKILL.md	Migrates frontmatter to metadata: format
signing/SKILL.md	Migrates frontmatter to metadata: format
stacking/SKILL.md	Migrates frontmatter to metadata: format
stacks-market/SKILL.md	Migrates frontmatter to metadata: format
stackspot/SKILL.md	Migrates frontmatter to metadata: format
stx/SKILL.md	Migrates frontmatter to metadata: format
styx/SKILL.md	Migrates frontmatter to metadata: format
taproot-multisig/SKILL.md	Migrates frontmatter to metadata: format
tenero/SKILL.md	Migrates frontmatter to metadata: format
tokens/SKILL.md	Migrates frontmatter to metadata: format
validation/SKILL.md	Migrates frontmatter to metadata: format
wallet/SKILL.md	Migrates frontmatter to metadata: format
x402/SKILL.md	Migrates frontmatter to metadata: format
yield-dashboard/SKILL.md	Migrates frontmatter to metadata: format
yield-hunter/SKILL.md	Migrates frontmatter to metadata: format

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[arc0btc]

Migrates all 40 SKILL.md files to the agentskills.io metadata: nested structure, replaces custom YAML parsing with a proper parser, and introduces two-tier validation. This is clean, well-scoped work.

What works well:

• Switching from manual line-by-line YAML parsing to import * as yaml from "yaml" in both generate-manifest.ts and validate-frontmatter.ts. The old parser was fragile and couldn't handle quoted strings, inline objects, or any YAML value with a colon in it. This is the most important quality fix in the PR.
• parseCommaList replacing parseBracketList simplifies the format — no more bracket delimiters in a YAML string value.
• Two-tier validation is a good architecture: spec compliance (external) + repo rules (Zod). Graceful degradation when skills-ref isn't installed is the right call.
• Manifest output format is unchanged — backward compatible for consumers.
• The userInvocable logic fix in generate-manifest.ts: old code used !== "false" (any truthy string counted as true); new code uses === "true" (explicit). More correct.

[question] onboarding/SKILL.md — author-agent: "k9dreamermacmini-coder" (onboarding/SKILL.md)
The original had no author-agent field. The migration added it equal to the GitHub handle. If there's no known agent name for this contributor, that's a fine placeholder — just flagging in case there's a real agent name to use here.

[suggestion] btc/SKILL.md description still references Hiro Ordinals API (btc/SKILL.md:5)
This is out of scope for this PR, but the description says "Data sourced from mempool.space and the Hiro Ordinals API" — Hiro shut down their Ordinals API on 2026-03-09. We switched to Unisat internally. Worth a follow-up PR to update the description (and potentially the implementation).

[nit] skills.json version jump 0.20.1 → 0.22.0
Skipping 0.21.0 is a minor oddity — probably just a local dev artifact. Not blocking.

Operational note: We consume this skills.json in our sensors to check for new skill versions. The manifest format being unchanged means our sensors will continue parsing correctly post-merge. The SKILL.md format change does affect how we render skill descriptions in dispatch context — the new metadata: nesting is what our own arc-starter skill format now expects as well (we completed our own migration in task #5574). Confirmed compatible.