feat: add Blocknative gas platform skill

[jolestar]

What

• add skills/blocknative-openapi-skill
• add a curated OpenAPI schema for a narrow Blocknative gas intelligence read surface
• update docs/skills.md

Why

Blocknative adds execution-time gas and fee intelligence that is still missing from the current skill set.

This PR keeps scope narrow and provider-first by wrapping the gas platform endpoints only: supported chains, block price confidence estimates, base fee prediction, and gas distribution.

How

• package the standard skill files: SKILL.md, agents/openai.yaml, references/usage-patterns.md, scripts/validate.sh
• scope v1 to /chains, /gasprices/blockprices, /gasprices/basefee-estimates, and /gasprices/distribution
• keep the skill read-only with explicit polling and coverage guardrails

Testing

• bash skills/blocknative-openapi-skill/scripts/validate.sh
• cargo fmt --check

Closes #308
Refs #168

[Copilot]

Pull request overview

Adds a new Blocknative Gas Platform wrapper skill to the skills catalog, including curated OpenAPI schema, usage/docs, and a validator script to enforce repository skill conventions.

Changes:

• Introduces skills/blocknative-openapi-skill with SKILL.md, OpenAI agent metadata, usage patterns, and validation script.
• Adds a curated OpenAPI schema for selected Blocknative gas intelligence endpoints.
• Updates docs/skills.md to list and document validation for the new skill.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
skills/blocknative-openapi-skill/SKILL.md	New skill documentation (setup, auth, workflow, guardrails).
skills/blocknative-openapi-skill/scripts/validate.sh	Adds skill-specific validation checks for docs + schema consistency.
skills/blocknative-openapi-skill/references/usage-patterns.md	Provides copy/paste usage examples for linking/auth/reads.
skills/blocknative-openapi-skill/references/blocknative-gas.openapi.json	Curated OpenAPI schema for /chains + gas price endpoints.
skills/blocknative-openapi-skill/agents/openai.yaml	Registers agent UI metadata + default prompt for the skill.
docs/skills.md	Adds the skill to the catalog + adds its validator command to maintenance docs.

---

💡 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.

[holonbot]

Review: PR #309 - feat: add Blocknative gas platform skill

Summary

This PR adds a new blocknative-openapi-skill to integrate Blocknative's gas intelligence APIs (gas prices, base fee estimates, and gas distribution) through UXC with a curated OpenAPI schema. The implementation follows the established patterns in the codebase and is well-scoped to read-only gas platform operations.

Overall Assessment: LGTM with minor suggestions

The PR successfully adds a narrow, provider-first gas intelligence skill that fills a gap in the current skill set. The code quality is high, follows existing conventions, and includes proper validation.

Key Findings

✅ Strengths

1. Follows established patterns: The skill structure closely matches existing openapi-skill implementations (alchemy, coinapi), including:

   • Standardized file structure (SKILL.md, agents/openai.yaml, references/, scripts/)
   • Consistent documentation flow with prerequisites, scope, auth, and workflow sections
   • Proper validation script with comprehensive checks

2. Well-scoped v1: Intentionally limits scope to read-only gas platform operations:

   • /chains - supported chain discovery
   • /gasprices/blockprices - gas price confidence estimates
   • /gasprices/basefee-estimates - base fee and blob fee prediction
   • /gasprices/distribution - pending gas distribution analysis

3. Good guardrails documentation: SKILL.md includes important usage boundaries:

   • Explicit read-only limitation
   • Polling frequency guidance ("at most once per second")
   • Auth standardization (recommends auth for all ops even if some work without it)
   • Coverage warnings (e.g., distribution being Ethereum-mainnet focused)

4. Proper auth configuration: Correctly uses Authorization header auth with clear setup instructions and validation commands.

5. Documentation updates: Properly updates docs/skills.md with the new skill in both the skills list and installation example.

🔍 Minor Suggestions

1. OpenAPI schema completeness (skills/blocknative-openapi-skill/references/blocknative-gas.openapi.json:309-486):
   The schema uses additionalProperties: true extensively. While this provides flexibility, consider whether the key properties are sufficiently documented. For v1, this is acceptable as it allows forward compatibility with Blocknative API additions.

2. Guardrail specificity (skills/blocknative-openapi-skill/SKILL.md:144):
   The polling guidance says "avoid tight polling loops" but doesn't specify a recommended minimum interval. Consider adding explicit guidance like "poll no more frequently than once per 5-10 seconds" to prevent accidental API abuse.

3. Error handling documentation (skills/blocknative-openapi-skill/SKILL.md:138-147):
   While the guardrails mention parsing stable fields (ok, kind, protocol, data, error), it would be helpful to add a brief example of handling the Blocknative-specific error response format in the usage patterns.

Validation Results

• ✅ Validation script passes: skills/blocknative-openapi-skill validation passed
• ✅ All required files present and properly structured
• ✅ OpenAPI schema is valid and includes expected paths
• ✅ Documentation is consistent with existing skills
• ⏳ cargo fmt --check in progress (installing Rust components)

No Blocking Issues

There are no correctness bugs, security issues, or compatibility problems that would block merge. The suggestions above are optional improvements for future iterations.

Recommendation

Approve - This PR is ready to merge. The implementation is solid, follows conventions, and adds valuable gas intelligence capabilities to the skill set.

[holonbot]

Additional Nit Suggestions

These are minor, non-blocking suggestions for future improvements:

1. Polling guidance specificity ()

The polling guidance says "avoid tight polling loops" but doesn't specify a recommended minimum interval. Consider adding explicit guidance like "poll no more frequently than once per 5-10 seconds" to prevent accidental API abuse and make the guardrail more actionable.

2. Error handling example ()

While the guardrails mention parsing stable fields (ok, kind, protocol, data, error), it would be helpful to add a brief example in usage-patterns.md showing how to handle the Blocknative-specific error response format to help users integrate more effectively.

---

These suggestions are optional and don't block merge.