chore: bump skillsaw to 0.16.0 and clear new strict warnings (#139)

Author: frederikprijck

.coderabbit.yaml

@@ -49,7 +49,7 @@ reviews:
         Scripts are executable code that AI agents can run.
         - Must be self-contained or clearly document dependencies.
         - Should include helpful error messages.
-        - Should handle edge cases gracefully.
+        - Should handle edge cases by exiting non-zero with an actionable message rather than crashing with a stack trace.
         - Check for security issues (command injection, credential leaks).
 
     - path: "plugins/auth0/.claude-plugin/**"

.github/workflows/skillsaw.yml

@@ -19,7 +19,7 @@ jobs:
     timeout-minutes: 10
     env:
       UV_PYTHON: "3.12"
-      SKILLSAW_VERSION: "0.4.3"
+      SKILLSAW_VERSION: "0.16.0"
     steps:
     - name: Checkout
       uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0

.skillsaw.yaml

@@ -1,6 +1,10 @@
 # skillsaw configuration
 # See https://github.com/stbenjam/skillsaw for more information
 
+# Pin to the skillsaw version this config targets so rules added in later
+# versions are enabled (see CI: .github/workflows/skillsaw.yml).
+version: "0.16.0"
+
 # Enable/disable rules with configurable severity levels
 rules:
   # Plugin Structure
@@ -73,11 +77,42 @@ rules:
     enabled: true
     severity: error
 
-  # Custom: Enforce openclaw metadata (emoji, homepage) in SKILL.md frontmatter
+  # Custom: presence check only — require the openclaw block plus emoji and
+  # homepage in SKILL.md frontmatter. Field *shape* validation (os, requires,
+  # install, ...) is delegated to the built-in openclaw-metadata rule below, so
+  # this rule intentionally does not re-validate those fields.
   skill-openclaw-metadata:
     enabled: true
     severity: error
 
+  # Built-in: validate the shape of every metadata.openclaw field (os values,
+  # requires/install structure, install kinds, archive types, ...). Ships with
+  # skillsaw and defaults to warning; promote to error so a malformed field
+  # fails CI the same way the presence check above does.
+  openclaw-metadata:
+    enabled: true
+    severity: error
+
+  # This repo's single skill is a router: SKILL.md is a detection/dispatch table
+  # (frameworks, intents, tooling) locked down by scripts/check_routing_evals.py
+  # and check_router_reachability.py, so its token budget is intentionally large
+  # and can't be trimmed without dropping routes. Raise the skill body warn limit
+  # to 4000 (still catches real bloat) while keeping the 6000 error ceiling. The
+  # skill-description budget (200) is unchanged and enforced separately.
+  context-budget:
+    limits:
+      skill:
+        warn: 4000
+        error: 6000
+
+  # validate-skill.sh is a CI-only structural gate (invoked from
+  # .github/workflows/skillsaw.yml), not agent-facing behavior the router should
+  # point at — same class as the rule's built-in tests/ exemption. Exempt it so
+  # it isn't flagged as an unreferenced/shadow file.
+  agentskill-unreferenced-files:
+    exclude:
+      - "scripts/validate-skill.sh"
+
 # Custom rules for marketplace-specific validation
 custom-rules:
   - ./.skillsaw/rules.py

.skillsaw/rules.py

@@ -486,24 +486,22 @@ def _parse_frontmatter(skill_md: Path) -> Optional[Dict[str, Any]]:
 
 class SkillOpenclawMetadataRule(Rule):
     """
-    Enforce that SKILL.md frontmatter includes metadata.openclaw with required fields.
+    Enforce that SKILL.md frontmatter declares the required metadata.openclaw block.
 
-    All skills must declare openclaw metadata for marketplace compatibility:
-    - metadata.openclaw.emoji (string, non-empty)
-    - metadata.openclaw.homepage (string, valid URL)
+    This rule is a *presence* check only: it guarantees every skill ships the
+    block plus the two fields we require for marketplace compatibility:
+    - metadata.openclaw.emoji (present, non-empty string)
+    - metadata.openclaw.homepage (present, valid URL)
 
-    Optional openclaw fields (not enforced but validated if present):
-    - metadata.openclaw.requires.bins (list of binary names)
-    - metadata.openclaw.os (list of OS identifiers, e.g., "darwin", "linux")
-    - metadata.openclaw.install (list of install definitions)
+    The *shape* of every other openclaw field (os, requires, install, ...) is
+    validated by skillsaw's built-in ``openclaw-metadata`` rule, enabled at
+    error severity in ``.skillsaw.yaml``. Keep this rule limited to presence so
+    the two do not duplicate (or contradict) each other.
     """
 
     # Simple URL pattern: must start with https://
     URL_RE = re.compile(r'^https?://\S+$')
 
-    # Valid OS identifiers
-    VALID_OS = {'darwin', 'linux', 'windows'}
-
     @property
     def rule_id(self) -> str:
         return "skill-openclaw-metadata"
@@ -554,134 +552,35 @@ def check(self, context: RepositoryContext) -> List[RuleViolation]:
                     )
                     continue
 
-                # Validate required fields
-                violations.extend(self._check_required_fields(openclaw, skill_md))
-
-                # Validate optional fields if present
-                violations.extend(self._check_optional_fields(openclaw, skill_md))
-
-        return violations
-
-    def _check_required_fields(self, openclaw: Dict[str, Any], skill_md: Path) -> List[RuleViolation]:
-        """Check that required openclaw fields are present and valid."""
-        violations = []
-
-        # emoji: must be a non-empty string
-        emoji = openclaw.get('emoji')
-        if not emoji or not isinstance(emoji, str) or not emoji.strip():
-            violations.append(
-                self.violation(
-                    "metadata.openclaw.emoji is missing or empty. "
-                    "Add an emoji identifier, e.g., 'emoji: \"\\U0001F510\"'.",
-                    file_path=skill_md
-                )
-            )
-
-        # homepage: must be a valid URL
-        homepage = openclaw.get('homepage')
-        if not homepage or not isinstance(homepage, str):
-            violations.append(
-                self.violation(
-                    "metadata.openclaw.homepage is missing. "
-                    "Add a homepage URL, e.g., 'homepage: https://github.com/auth0/agent-skills'.",
-                    file_path=skill_md
-                )
-            )
-        elif not self.URL_RE.match(homepage):
-            violations.append(
-                self.violation(
-                    f"metadata.openclaw.homepage '{homepage}' is not a valid URL. "
-                    "Must start with http:// or https://.",
-                    file_path=skill_md
-                )
-            )
-
-        return violations
-
-    def _check_optional_fields(self, openclaw: Dict[str, Any], skill_md: Path) -> List[RuleViolation]:
-        """Validate optional openclaw fields if they are present."""
-        violations = []
-
-        # requires.bins: if present, must be a list of non-empty strings
-        requires = openclaw.get('requires')
-        if requires is not None:
-            if not isinstance(requires, dict):
-                violations.append(
-                    self.violation(
-                        "metadata.openclaw.requires must be a mapping. "
-                        "Example: 'requires:\\n  bins:\\n    - auth0'.",
-                        file_path=skill_md
-                    )
-                )
-            else:
-                bins = requires.get('bins')
-                if bins is not None:
-                    if not isinstance(bins, list) or not all(
-                        isinstance(b, str) and b.strip() for b in bins
-                    ):
-                        violations.append(
-                            self.violation(
-                                "metadata.openclaw.requires.bins must be a list of non-empty strings. "
-                                "Example: 'bins:\\n  - auth0'.",
-                                file_path=skill_md
-                            )
-                        )
-
-        # os: if present, must be a list of valid OS identifiers
-        os_list = openclaw.get('os')
-        if os_list is not None:
-            if not isinstance(os_list, list) or not os_list:
-                violations.append(
-                    self.violation(
-                        "metadata.openclaw.os must be a non-empty list. "
-                        f"Valid values: {', '.join(sorted(self.VALID_OS))}.",
-                        file_path=skill_md
-                    )
-                )
-            else:
-                invalid = [o for o in os_list if o not in self.VALID_OS]
-                if invalid:
+                # emoji: must be a non-empty string
+                emoji = openclaw.get('emoji')
+                if not emoji or not isinstance(emoji, str) or not emoji.strip():
                     violations.append(
                         self.violation(
-                            f"metadata.openclaw.os contains invalid entries: {invalid}. "
-                            f"Valid values: {', '.join(sorted(self.VALID_OS))}.",
+                            "metadata.openclaw.emoji is missing or empty. "
+                            "Add an emoji identifier, e.g., 'emoji: \"\\U0001F510\"'.",
                             file_path=skill_md
                         )
                     )
 
-        # install: if present, must be a list of dicts with required keys
-        install = openclaw.get('install')
-        if install is not None:
-            if not isinstance(install, list):
-                violations.append(
-                    self.violation(
-                        "metadata.openclaw.install must be a list of install definitions.",
-                        file_path=skill_md
-                    )
-                )
-            else:
-                for i, entry in enumerate(install):
-                    if not isinstance(entry, dict):
-                        violations.append(
-                            self.violation(
-                                f"metadata.openclaw.install[{i}] must be a mapping with "
-                                "'id', 'kind', 'formula', 'bins', and 'label' fields.",
-                                file_path=skill_md
-                            )
+                # homepage: must be present and a valid URL
+                homepage = openclaw.get('homepage')
+                if not homepage or not isinstance(homepage, str):
+                    violations.append(
+                        self.violation(
+                            "metadata.openclaw.homepage is missing. "
+                            "Add a homepage URL, e.g., 'homepage: https://github.com/auth0/agent-skills'.",
+                            file_path=skill_md
                         )
-                        continue
-                    missing = [
-                        k for k in ('id', 'kind', 'formula', 'bins', 'label')
-                        if not entry.get(k)
-                    ]
-                    if missing:
-                        violations.append(
-                            self.violation(
-                                f"metadata.openclaw.install[{i}] is missing required fields: "
-                                f"{', '.join(missing)}.",
-                                file_path=skill_md
-                            )
+                    )
+                elif not self.URL_RE.match(homepage):
+                    violations.append(
+                        self.violation(
+                            f"metadata.openclaw.homepage '{homepage}' is not a valid URL. "
+                            "Must start with http:// or https://.",
+                            file_path=skill_md
                         )
+                    )
 
         return violations
 

.snyk-agent-scan-ignore.json

@@ -11,19 +11,19 @@
   },
   {
     "code": "W012",
-    "skills": ["auth0-swift"],
+    "skills": ["auth0"],
     "url": "https://github.com/auth0/Auth0.swift",
     "reason": "First-party Auth0 Swift SDK repository"
   },
   {
     "code": "W012",
-    "skills": ["acul-screen-generator"],
+    "skills": ["auth0"],
     "url": "https://github.com/auth0-samples/auth0-acul-samples/tree/main/react/src/screens/<screen-name>",
     "reason": "First-party Auth0 samples repository for ACUL screen examples"
   },
   {
     "code": "W012",
-    "skills": ["acul-screen-generator"],
+    "skills": ["auth0"],
     "url": "https://github.com/auth0/universal-login/blob/master/packages/auth0-acul-react/examples/<screen-name>",
     "reason": "First-party Auth0 universal-login repository"
   },
@@ -34,13 +34,13 @@
   },
   {
     "code": "W012",
-    "skills": ["auth0-branding"],
+    "skills": ["auth0"],
     "url_pattern": "https://api\\.brandfetch\\.io/v2/brands/",
     "reason": "Brandfetch API is used to extract brand tokens (colors, logos, fonts) for theming Auth0 Universal Login"
   },
   {
     "code": "W012",
-    "skills": ["auth0-custom-domains"],
+    "skills": ["auth0"],
     "url": "https://mcp.cloudflare.com/mcp",
     "reason": "The skill sets up custom domains for Auth0 tenants, and uses Cloudflare's MCP to write the CNAME record for the custom domain."
   },

AGENTS.md

@@ -5,7 +5,8 @@ Guidance for AI coding agents working in this repository.
 ## What this repo is
 
 An **Agent Skill** that teaches coding assistants how to implement Auth0
-authentication correctly. It ships as a single Claude Code / Cursor / Copilot
+authentication that follows Auth0's documented SDK usage and passes this
+repo's routing and behavioral evals. It ships as a single Claude Code / Cursor / Copilot
 plugin (`auth0`) containing **one** consolidated skill at
 `plugins/auth0/skills/auth0/`: a router `SKILL.md` over a flat pool of on-demand
 reference files. The deliverable is the skill itself.

CONTRIBUTING.md

@@ -51,13 +51,13 @@ Your `SKILL.md` must include:
        requires:                           # optional: declare external dependencies
          bins:
            - auth0                         # declare `auth0` if the skill runs CLI commands
-       os:                                 # optional: darwin, linux, windows
+       os:                                 # optional: darwin, linux, win32
          - darwin
          - linux
        install:                            # optional: how to install required bins
          - id: brew
            kind: brew
-           package: auth0/auth0-cli/auth0
+           formula: auth0/auth0-cli/auth0
            bins: [auth0]
            label: 'Install Auth0 CLI (brew)'
    ---