[deepujain]

Closes #1270.

What Problem This Solves

A skill declaring env: RISKSTATE_API_KEY loses that credential declaration when ClawHub builds its installation and scanner metadata.

User Impact

Newly published versions retain the key as a required credential in installation guidance and scanner input. Stored metadata is not backfilled; publishing a new version refreshes it.

Why This Change Was Made

The parser already accepts top-level env arrays. This extends that fallback to one valid variable name while preserving structured metadata precedence and optional declarations. Assignments and lists in scalar text are ignored. The documentation continues to recommend metadata.openclaw.requires.env for new skills.

There is no schema migration or CLI release. The backend change takes effect through the normal manual deployment.

Evidence

The scanner regression fails on main at 907b6398 because the required key is missing, and passes on ac738e07.

On ac738e07, the shipped ClawHub CLI published scalar-env-proof@1.0.0 to a disposable local Convex backend running this revision. Its SKILL.md declared env: RISKSTATE_API_KEY. The public skill API returned this installation setup:

[{"key":"RISKSTATE_API_KEY","required":true}]

The scanner claim API returned the published version's queued job. The worker downloaded SKILL.md, verified its hash, and retained this normalized version metadata in its workspace:

{"envVars":[{"name":"RISKSTATE_API_KEY","required":true}]}

Convex typechecking passed before publication. Prepublication scan results were simulated using the repository's local-test protocol, with the VirusTotal wait set to zero. No external model verdict, VirusTotal scan, or production publication was run.

• bunx vitest run convex/lib/skills.test.ts convex/lib/securityPrompt.test.ts --maxWorkers=2: 63 tests passed.
• bun run ci:static: passed.
• bun run ci:unit --maxWorkers=2 on Linux: 8,366 tests passed, five skipped, and coverage thresholds passed.
• bun run ci:types-build: passed, including root, schema, CLI and admin TypeScript checks and the production build.

Bun 1.4.4 was used throughout, with Node 24.22.1 for the runtime and build checks and Node 22.19.0 for Linux unit validation. The macOS coverage run timed out in the unchanged Mermaid fallback test; the complete gate passed on Linux.

Evidence for ClawSweeper's publication-proof request is included above. Current-head automated review is pending.

AI-assisted contribution. I reviewed the implementation and tests and can maintain this change.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[vercel]

@deepujain is attempting to deploy a commit to the OpenClaw Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[clawsweeper]

Codex review: needs real behavior proof before merge.

What this changes

The PR parses a single top-level env name into required environment metadata while preserving structured metadata precedence.

Example: Publish a skill containing env: RISKSTATE_API_KEY without a structured metadata block.

• Before: The parser omits the credential declaration from normalized metadata.
• After: The parser produces envVars: [{ name: "RISKSTATE_API_KEY", required: true }] for installation guidance and scanner input.

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The patch is focused and source-correct, but the required real-behavior proof is absent.
Proof confidence	🧂 unranked krab (1/6)	Real behavior proof is necessary before merge. See Before merge.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: A declared credential disappears from installation and scanner metadata when a publisher uses a single top-level env name.
Reason: The patch repairs the existing fallback at its shared owner, documents its boundary, and preserves optional declarations without adding configuration or promising a clean scan verdict.

Merge readiness

⛔ Blocked before merge - 1 item remains

Keep open: current main still drops scalar env declarations, and this PR provides a focused repair with no identified code defects.

Priority: P2
Reviewed head: bef387a3bb54999ac2a37a5914c963304d74d190

Before merge

• Add real behavior proof - The parser-to-prompt regression exercises real helpers in unit tests, but the supplied evidence does not show a published scalar-env version reaching installation guidance and scanner input through the shipped workflow; provide screenshots, redacted logs, or live output for that scenario, redacting credentials, IPs, and non-public endpoints. After adding proof, update the PR body, then request a new review with @clawsweeper re-review. The PR author or someone with repository write access can request it.

Findings

None.

Tests

• Missing end-to-end proof: Missing supplied proof of publishing a scalar-env skill through ClawHub and observing the retained declaration in installation guidance and actual scanner input.

Agent review details

How this fits together

The skill publishing pipeline parses SKILL.md frontmatter into stored version metadata consumed by the setup API, installation card, and security scanner.

flowchart LR
  A[Published SKILL.md] --> B[Frontmatter parser]
  B --> C[Metadata normalization]
  C --> D[Stored version metadata]
  D --> E[Installation guidance]
  D --> F[Scanner prompt]

Loading

Technical review

Best possible solution:

Land the narrow normalization in the existing fallback while retaining canonical metadata precedence and leaving historical versions unchanged.

Do we have a high-confidence way to reproduce the issue?

Yes at source level: main routes env: RISKSTATE_API_KEY into an array-only parser, which discards it; no target code or tests were run during this read-only review.

Is this the best way to solve the issue?

Best-fix verdict: best; normalizing only the top-level scalar preserves existing structured declarations, whereas changing the shared declaration parser would also broaden namespaced inputs and changing scanner or UI consumers would duplicate normalization.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against c9a9fe2ed4c4.

Provenance checked

• Top-level environment declarations keeps the original intent (db45407: The merged manifest work added env declarations and a top-level fallback to keep registry metadata aligned with skill credential requirements; its array-only implementation omitted scalar shorthand.)
• Structured metadata precedence and optional variables keeps the original intent (52078ab: The merged optional-env clarification preserved required-variable behavior and represented optional variables through envVars with required: false.)

Testing

Proof path: unit tests only.

Security

None.

Evidence

What I checked:

• Exact introduced change: The pinned diff contains one production change: scalar-name normalization in the existing top-level fallback, accompanied by parser and scanner tests, documentation, a spec, and a changelog entry. (convex/lib/skills/index.ts:506, bef387a3bb54)
• Current main retains the bug: Main passes frontmatter.env directly to parseEnvVarDeclarations, which returns an empty list for non-arrays; the reported scalar therefore produces no declaration. (convex/lib/skills/index.ts:506, c9a9fe2ed4c4)
• Production consumers support the normalized shape: Publishing stores parseClawdisMetadata output in parsed.clawdis; the installation card and setup API already consume envVars, and the scanner prompt displays required declarations from that field. (convex/lib/skillPublish.ts:265, bef387a3bb54)
• Original fallback intent: Merged feat(registry): support env vars, dependencies, author, and links in skill manifest #360 introduced structured env declarations and the top-level fallback to prevent scanner metadata mismatches; its original implementation accepted arrays only. (convex/lib/skills.ts:402, db4540743f84)
• Related parser and optional-env contracts: Merged fix: extract requires.env and homepage from top-level frontmatter #548 added top-level requires.env extraction, while docs: clarify optional skill environment variables #1859 documented optional envVars; this patch preserves both paths. (docs/skill-format.md:84, 52078abd85d0)
• Linked report and prior discussion: env frontmatter field not parsed into registry metadata ("Required env vars: none") #1270 reports the exact RISKSTATE_API_KEY scalar. Its discussion distinguishes that gap from a nested metadata report already supported by source. The earlier False positive: riskstate skill flagged as suspicious #1144 concerns the skill's moderation outcome, which does not establish that scalar parsing is fixed.

Likely related people:

• Mahsum Aktaş: Raw commit db45407 adds convex/lib/skills.ts:325 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: db4540743f84; files: convex/lib/skills.ts)
• Munem Hashmi: Raw commit 40a89e0 adds convex/lib/skills.ts:402 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 40a89e02d53e; files: convex/lib/skills.ts)
• Deepak Jain: Raw commit 52078ab adds docs/skill-format.md:71 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 52078abd85d0; files: docs/skill-format.md)
• Patrick Erichsen: Raw commit 70fd943 adds convex/lib/skills.ts:435 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 70fd9436cf9f; files: convex/lib/skills.ts)

Review metrics

Metric	Value	Why it matters
Change size	Production +5/-1; tests +38/-0; documentation and changelog +9/-0	The implementation stays inside the existing parser owner, with focused coverage for the reported input, invalid names, and metadata precedence.

Labels

Label changes:

• add P2: Missing credential declarations affect installation guidance and scanner context for a bounded frontmatter shape.
• add rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Label justifications:

• P2: Missing credential declarations affect installation guidance and scanner context for a bounded frontmatter shape.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🧂 unranked krab and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 29, 2026, 4:03 AM ET / 08:03 UTC.