Misinformation & Unexpanded Templates

Open
  • Is something wrong?
#249 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Active
Tech stack
bash, go, google-cloud, markdown
Domain
documentation

Research direction

Start with the listed files: ai_agg.md, assess_integration.sh, and the four Genkit Go reference documents. Check the companion Apigee skill guides for SDK version requirements, then review each reported template placeholder and Go signature in context. Done means the documentation is accurate and consistently rendered, with the SDK guidance aligned to the script; the issue does not name tests or a validation command.

Written by the indexing model from the issue text.

Description

Misinformation & Unexpanded Templates
A. Raw Unexpanded Documentation Template Variables
  • Issue Type: Unprocessed Template Macro / Documentation Defect
  • Affected File: skills/cloud/bigquery-ai-ml/references/ai_agg.md (Line 32)
Description

In the argument reference for BigQuery AI.AGG, an internal documentation template variable is left unrendered in the published markdown text:

"ObjectRefRuntime values reference text or image data in {{gcs_name}} and are generated by the OBJ.GET_ACCESS_URL function..."

Impact
  • Incomplete / Corrupted Technical Reference: The string {{gcs_name}} was copied from internal Google documentation source templates without running the corresponding macro preprocessor.
  • Ambiguity for End Users: Readers and AI agents parsing the documentation encounter raw template placeholders rather than the intended service name (Cloud Storage / Google Cloud Storage).
Recommended Remediation

Replace the raw template token with the explicit service name:

`ObjectRefRuntime` values reference text or image data in Google Cloud Storage and are generated by the `OBJ.GET_ACCESS_URL` function...
B. Toolchain Version Drift and Conflicting Minimum Requirements
  • Issue Type: Version Inconsistency / Inaccurate Prerequisites
  • Affected File: skills/cloud/apigee-agent-gateway-governance/scripts/assess_integration.sh (Lines 179–185)
Description

The script contains historical comments documenting version drift between the skill's instructions and actual CLI command availability:

MAJOR="${GCV%%.*}"
# 588.0.0 is where `apis import --from-template` reached the GA track. Below
# it the GA command rejects the flag with an error that reads like the
# command does not exist, and `gcloud beta` is the fallback. This check used
# to say 585, which disagreed with every other statement of the minimum in
# this skill and would have passed an SDK the build then failed on.
if (( MAJOR < 588 )); then
  record WARN "gcloud" "$GCV -- below 588.0.0; 'apis import --from-template' is GA only from 588, use 'gcloud beta' or upgrade"
Impact
  • Documentation Desynchronization: While the validation script was patched to check for 588.0.0, companion markdown references in the skill still cite older SDK baselines or fail to clarify that gcloud beta is strictly required for environments below version 588.
  • Build Failures in CI/CD: Developers running standard GCP SDK installations between versions 585 and 587 receive misleading error messages indicating that the command or flag does not exist.
Recommended Remediation

Ensure all markdown guides, prerequisites, and automated validation scripts across the skill consistently specify Google Cloud SDK version 588.0.0 or higher (or explicitly instruct the use of gcloud beta apis import --from-template).

C. Documentation Rendering Corruption from Unshielded Go Generic Signatures
  • Issue Type: Markdown Parsing Conflict / Syntax Collision
  • Affected Files:
    • skills/cloud/developing-genkit-go/references/agents-custom.md (Line 27)
    • skills/cloud/developing-genkit-go/references/agents-artifacts.md (Line 26)
    • skills/cloud/developing-genkit-go/references/agents-state.md (Line 40)
    • skills/cloud/developing-genkit-go/references/agents-sessions.md (Line 26)
Description

In several Genkit Go reference documents, Go generic type parameter declarations (e.g., [State any](...) or [T any](...)) occur in text or table columns without enclosing backticks:

func DefineCustomAgent[State any](<g *genkit.Genkit, name string, ...>)
Impact
  • Misparsed Markdown Hyperlinks: Standard CommonMark and GitHub Flavored Markdown parsers interpret [State any](...) as a Markdown link with link text "State any" and URL target "(g *genkit.Genkit, ...)".
  • Corrupted Rendered Text: In web renderers, documentation readers, and static site generators, function parameter signatures become broken clickable blue links that resolve to 404 targets, stripping brackets and garbling type definitions.
Recommended Remediation

Wrap all function signatures, type parameters, and Go generics inside inline code backticks (e.g., `[State any]`) or fenced code blocks to prevent Markdown link parser collisions.

Dominant language
Python
Stars
23.1k
Forks
1.9k
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from google/skills

All issues in google/skills

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.