Goal

Align Netclaw skill ingestion and authoring with the AgentSkills.io specification so skill discovery is portable, deterministic, and context-efficient.

Why

Current skill plumbing is markdown-comment based (e.g. <!-- description: ... -->, <!-- triggers: ... -->) and does not fully match the open standard (SKILL.md + YAML frontmatter). As the skill ecosystem grows, this makes interoperability and routing quality harder.

Standards target

Use the AgentSkills.io spec as baseline:

• required SKILL.md per skill directory
• YAML frontmatter with required metadata:
  • name
  • description (includes when-to-use cues)
• progressive/contextual discovery:
  • load only metadata at startup
  • activate by loading full SKILL.md only when relevant
• optional standard fields where useful (compatibility, metadata, allowed-tools)

Reference:

• https://agentskills.io/specification.md
• https://agentskills.io/integrate-skills.md

Scope proposal

1. Scanner/registry refactor
   • Discover skills by */SKILL.md convention.
   • Parse YAML frontmatter metadata.
   • Preserve backward compatibility for legacy .md skills during migration window.
2. Contextual discovery plumbing
   • Keep startup metadata compact.
   • Improve matching/routing signals from standardized frontmatter + descriptions.
3. Authoring docs + templates
   • Update skill-authoring guidance to frontmatter-first format.
   • Add canonical skill template generated by CLI/workflow.
4. Validation gates
   • Add validation checks in tests and/or CI for frontmatter schema and name/path consistency.
   • Optionally use skills-ref validate in dev workflow.
5. Migration plan
   • Convert system skills to SKILL.md format.
   • Define deprecation timeline for legacy comment metadata.

Acceptance criteria

• Netclaw can discover and index AgentSkills.io-compliant skills with frontmatter.
• Agent prompt context includes concise metadata only until activation.
• Skill activation/retrieval behavior remains stable or improves under load.
• Existing built-in/system skills are migrated or compatibility shim is documented.

Related

• Improve skill guidance for Playwright screenshot handoff and simplify skill routing #149 (screenshot handoff workflow and trigger quality)