Skip to content

Align frontmatter with Agent Skills spec#55

Merged
raymondk merged 5 commits intomainfrom
marc0olo/align-agent-skills-spec
Mar 2, 2026
Merged

Align frontmatter with Agent Skills spec#55
raymondk merged 5 commits intomainfrom
marc0olo/align-agent-skills-spec

Conversation

@marc0olo
Copy link
Copy Markdown
Member

@marc0olo marc0olo commented Mar 2, 2026

Summary

  • Migrate all 13 skills to Agent Skills spec-compliant frontmatter: name, description, license, compatibility, metadata.title, metadata.category
  • Remove non-spec fields: version, endpoints, status, dependencies, requires, tags
  • Delete ai-plugin.json endpoint and generate-readme-table.js script
  • Simplify CI, validator, site components, and all documentation
  • Add Apache-2.0 LICENSE file
  • Net -404 lines across 33 files

Changes by area

Frontmatter (all 13 skills + template + schema):
New format:

name: ckbtc
description: "..."
license: Apache-2.0
compatibility: "icp-cli >= 0.1.0"
metadata:
  title: ckBTC Integration
  category: DeFi

Site:

  • Remove version badge, endpoints count, status badge, dependency links from browse/detail pages
  • Remove redundant Before/After section from How It Works page
  • Align anatomy section with README structure table (6 rows, same names)
  • Remove redundant Quick Start terminal from Access page
  • Fix header width jumping between pages (consistent 1200px nav)
  • Fix "Versioned in frontmatter" → "Git-tracked with last-updated dates"

Docs (README, CONTRIBUTING, CLAUDE.md):

  • Collapse Usage from ~80 lines (per-agent sections) to ~12 lines (CLI + manual)
  • Downgrade unknown categories from error to warning
  • Relax body sections to recommendations (warnings), not requirements (errors)
  • Slim template from 145 to 68 lines (guidance comments instead of skeleton code)

CI & tooling:

  • Simplify _checks.yml from 3 steps to 1 (npm ci + node scripts/validate-skills.js)
  • Remove generate script from package.json, update build to validate && astro build
  • Delete scripts/generate-readme-table.js
  • Delete src/pages/.well-known/ai-plugin.json.ts

Closes #45

… docs

Migrate all 13 skills to spec-compliant frontmatter format:
- Required: name, description, metadata.title, metadata.category
- Optional: license (Apache-2.0), compatibility (icp-cli >= 0.1.0)
- Removed: version, endpoints, status, dependencies, requires, tags

Site and tooling:
- Delete ai-plugin.json endpoint (non-functional OpenAI format)
- Delete generate-readme-table.js (merge conflict magnet)
- Simplify CI from 3 steps to 1 (validate only)
- Remove version/endpoints/status/dependencies from components
- Fix header width jumping between pages (consistent 1200px)
- Remove redundant Before/After section from how-it-works
- Align anatomy section with README structure table
- Remove Quick Start terminal from Access page (redundant)
- Slim down template from 145 to 68 lines

Docs:
- Simplify README Usage to CLI + manual (was per-agent sections)
- Downgrade categories from error to warning
- Relax body sections to recommendations, not requirements
- Add LICENSE file (Apache-2.0)
- Update CLAUDE.md and CONTRIBUTING.md for new format

Closes #45
marc0olo added 2 commits March 2, 2026 13:35
The `compatibility` field covers environment requirements broadly
(tools, system packages, network access) — not just CLI tools.
This aligns with the Agent Skills spec definition. Library/SDK
dependencies still go in the Prerequisites section.
The compatibility field covers environment requirements broadly
(tools, system packages, network access) — not just CLI tools.
Updated examples in template and CONTRIBUTING.md to reflect this.
Library/SDK dependencies belong in the Prerequisites section.
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented Mar 2, 2026

Update: compatibility vs Prerequisites clarification

Added two commits clarifying the compatibility field:

  • compatibility = environment requirements (tools, system packages, network access) — aligned with the Agent Skills spec definition
  • ## Prerequisites = library/SDK dependencies (language-specific crates, npm packages, mops packages)

Updated the template, CONTRIBUTING.md, and CLAUDE.md to reflect this distinction clearly.

Follow-up needed: 3 skills (ckbtc, evm-rpc, internet-identity) have minor version gaps in their Prerequisites sections (libraries listed without minimum versions). This will be addressed in a separate PR that makes all skills consistent.

marc0olo added 2 commits March 2, 2026 13:44
Prerequisites section is for library/SDK versions, not environment
requirements. Updated example from icp-cli to ic-cdk and @icp-sdk/auth.
Helps prevent overtriggering — agents loading a skill when a
similar-but-wrong one matches. Pattern already used in draft skills.
Comment thread src/layouts/SiteLayout.astro
@raymondk raymondk merged commit 5504d7d into main Mar 2, 2026
6 checks passed
@raymondk raymondk deleted the marc0olo/align-agent-skills-spec branch March 2, 2026 15:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Align frontmatter with Agent Skills specification

2 participants