feat: Add query-index-optimizer skill for EDS content ops by focusgts · Pull Request #189 · adobe/skills

focusgts · 2026-06-15T14:41:08Z

Summary

Adds the query-index-optimizer skill to the EDS content ops plugin.

Audits and tunes the query index — analyzes indexed properties against actual usage, checks index size and pagination, and generates helix-query.yaml recommendations.

Follows the established format (functional description, External Content Safety, concrete code examples, reference file for progressive disclosure, Apache-2.0). Submitted as a standalone PR per @trieloff's request to keep one skill per PR.

Test plan

tessl-review passes (≥80

trieloff · 2026-06-15T20:15:46Z

@dominique-pfister this seems to be your area of expertise, can you take a look, please?

dominique-pfister · 2026-06-29T11:19:14Z

+
+### Key Concepts
+
+- **helix-query.yaml** — Lives in the GitHub repo root. Defines which properties to index and how they are sourced (from metadata, headings, or content).


This is no longer true: it lives in the configuration, see: https://www.aem.live/developer/indexing#setting-up-an-initial-index-with-the-index-admin-tool

dominique-pfister · 2026-06-29T11:19:42Z

+### Key Concepts
+
+- **helix-query.yaml** — Lives in the GitHub repo root. Defines which properties to index and how they are sourced (from metadata, headings, or content).
+- **query-index.json** — The live JSON endpoint. Returns an array of page entries with the indexed properties.


This is just the default name of the query index, it can also be named differently.

dominique-pfister · 2026-06-29T11:20:48Z

+- **helix-query.yaml** — Lives in the GitHub repo root. Defines which properties to index and how they are sourced (from metadata, headings, or content).
+- **query-index.json** — The live JSON endpoint. Returns an array of page entries with the indexed properties.
+- **Consumers** — Blocks and components that fetch `query-index.json` to build dynamic lists: navigation, footer, card lists, search results, recent posts, tag-filtered collections.
+- **Default limit** — The index returns a maximum of 500 entries by default. Sites with more pages need to paginate or increase the limit.


Wrong, it returns 1000 entries by default, as documented here: https://www.aem.live/developer/spreadsheets#offset-and-limit

dominique-pfister · 2026-06-29T11:21:34Z

+- **query-index.json** — The live JSON endpoint. Returns an array of page entries with the indexed properties.
+- **Consumers** — Blocks and components that fetch `query-index.json` to build dynamic lists: navigation, footer, card lists, search results, recent posts, tag-filtered collections.
+- **Default limit** — The index returns a maximum of 500 entries by default. Sites with more pages need to paginate or increase the limit.
+- **Index freshness** — The index updates when pages are previewed or published via Sidekick. Unpublished pages remain in the index until explicitly removed.


Wrong, should be:

The index updates when pages are published. (via Sidekick or programmatically does not matter)

dominique-pfister · 2026-06-29T11:22:24Z

+
+## How the EDS Query Index Works
+
+The query index is the primary mechanism for blocks and components to discover and list content in an EDS site. It is configured via a `helix-query.yaml` file in the GitHub repository and served as JSON at `/query-index.json`.


No, configured via Index Admin: https://www.aem.live/developer/indexing#setting-up-an-initial-index-with-the-index-admin-tool

dominique-pfister

Already found 4 errors in the first few lines that are repeated later, please fix and align with the current documentation.

@dominique-pfister

…docs Address @dominique-pfister review: - Index is configured via the Index Admin tool / Admin API, not a helix-query.yaml file in the GitHub repo - query-index.json is the default index name; indices can be named differently - Default entry limit is 1000, not 500 (per the spreadsheets doc) - Pages are indexed on publish, not preview - Cite the indexing and spreadsheets docs as sources of truth Co-Authored-By: claude-flow <ruv@ruv.net>

focusgts · 2026-06-29T15:45:24Z

Thanks @dominique-pfister — these are exactly right, and I appreciate the careful review with the doc links. I've corrected all four against the current docs: index configured via the Index Admin tool (not a repo helix-query.yaml), query-index.json as the default name, the 1000-entry default limit per the spreadsheets doc, and indexing on publish. I also cited the indexing and spreadsheets docs as sources of truth in the reference file. The fix is pushed.

You're right that these repeat — we're doing a documentation-grounded pass over the rest of our skills to catch the same class of staleness. Appreciate you keeping the bar high.

focusgts · 2026-06-29T16:32:26Z

@dominique-pfister @trieloff — your review here prompted us to audit our entire content-ops suite against the current aem.live docs, not just this skill. We found the same class of staleness (the helix-query.yaml → Index Admin change, the 1000-entry default, publish-vs-preview indexing, and a few others such as the current helix-sitemap.yaml schema and the RUM Bundler API shape) in several already-merged skills, and we have doc-grounded corrections ready, each cited to an aem.live page.

Would you prefer one PR per skill (per the usual process here) or a single batched corrections PR? Happy to do whichever is easiest to review. Thanks again — the review made the whole set better.

trieloff · 2026-07-06T15:34:39Z

One PR per skill, please.

…tion

focusgts · 2026-08-10T20:02:20Z

cc @trieloff

Friendly nudge — Dominique's four corrections were fixed and pushed on June 29, each aligned with the current aem.live docs and cited in the reference file.

And understood on one PR per skill for the corrections to the already-merged skills — we'll submit those individually. Anything else needed on this one? (The red tessl-review is the fork-secrets auth issue — ✘ Please authenticate with Tessl to continue — same as on #186 when it merged.)

focusgts · 2026-08-20T19:00:51Z

Thanks @dominique-pfister. All five are fixed and aligned with the current docs. Index configuration is now described as managed via the Index Admin tool (not a repo file), query-index.json is called out as the default name (sites can define others), the default limit is corrected to 1000 with the offset/limit doc linked, and the index is described as updating when pages are published (Sidekick or programmatic, the method does not matter). Ready for another look whenever you have a moment.

trieloff · 2026-08-21T10:06:07Z

The failing tessl-review check here is not a problem with this skill — it's a CI limitation.

This PR comes from a fork, and GitHub does not expose repository secrets to workflow runs triggered by pull_request from forks. So secrets.TESSL_TOKEN was empty, setup-tessl installed an unauthenticated CLI, and the review bailed immediately:

✘ Please authenticate with Tessl to continue. Run `tessl login` to sign up or log in.
##[warning]tessl review run failed for query-index-optimizer (exit code 1)

The workflow then counts that tool/auth error as a failure and reports it as 1 skill(s) scored below 80% — but the skill was never actually scored.

Local review result

I ran the review locally against this PR's head (cbfa302):

Review Score: 85% — passes the 80% threshold.

Validation: PASSED (0 errors, 0 warnings), all 16 checks green
Description: 93% — specificity 5/5, trigger terms 4/5, completeness 5/5, distinctiveness 5/5
Content: 71% — conciseness 3/5, actionability 4/5, workflow clarity 4/5, progressive disclosure 5/5

Optional polish the judge suggested, if you'd like to raise the content score:

Trim the "When to Use" section and drop explanations of things the agent already knows (what card blocks do, what consumers are).
Add executable snippets for Steps 4–5 (sitemap fetch/parse, HTTP status checking) rather than describing the process in prose.
Add a validation checkpoint between Steps 2 and 3 to confirm the index definition matches the live index output before mapping consumers.

None of these are blocking — the skill passes as-is.

I'm opening a separate PR to fix the workflow so fork PRs are handled properly (skipped cleanly when the token isn't available, instead of reported as a quality failure).

trieloff · 2026-08-21T10:10:34Z

Follow-up: the workflow fix is up as #308 — it makes fork PRs work, drops the deprecated tessl skill review call, pins the checkout, and stops reporting auth/tooling failures as low scores. Once that lands, re-running this check should score this skill properly.

trieloff · 2026-08-21T10:40:00Z

Correction to my earlier comments — I was working from a stale checkout of main and got the "what needs fixing" part wrong.

The root cause I described is right: that run was an unauthenticated Tessl CLI, because pull_request withholds secrets from fork runs. But it had already been fixed by the time I looked.

This run: 2026-07-07T08:49:32Z
ci: allow tessl review on fork PRs via gated eval environment (e56e29f): 2026-07-07T10:01:48Z
ci: only gate fork PRs, not same-repo (maintainer) PRs (756e8d7): 2026-07-07T10:23:40Z

So the fix landed about 72 minutes after this run. main today already uses pull_request_target with the eval environment gating fork PRs, and already uses tessl review run --workspace --json --threshold. Nothing about the workflow needs changing for this PR to pass — please disregard my earlier note about #308 being required here.

The red check above is simply stale. It is over a month old, so GitHub will not let it be re-run directly. Re-triggering it needs a new commit on the branch, or the branch to be updated from main (this PR is a month behind). Either will produce a fresh run against the current, working workflow.

My local review result stands and is unchanged — this skill scores 85% and passes the 80% threshold.

When the Tessl CLI fails to run at all — auth failure, network error, crash — the job counted it as a review failure and reported it as "N skill(s) scored below 80%". That is misleading: the skill was never scored. On #189 this surfaced as a red "below 80%" check on a skill that actually scores 85%, which reads to a contributor as a quality rejection. Track those separately as errors and report them as "review could not be run", with a ⚠️ row and an explanatory note in the step summary. They still fail the job — they are just no longer confused with low scores. Also: - Skip cleanly with an explanatory summary when TESSL_TOKEN is not configured, instead of running an unauthenticated CLI and failing. - Pin actions/checkout and tesslio/setup-tessl to commit SHAs, with `# vN` comments so Renovate keeps tracking them. - Add a concurrency group so superseded runs are cancelled. - Use a single redirect block in the skip summary, silencing the one actionlint/shellcheck warning (SC2129) in this file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Signed-off-by: Lars Trieloff <lars@trieloff.net>

@trieloff

… the fixed fork-PR workflow (per @trieloff review on adobe#189)

@trieloff

… the fixed fork-PR workflow (per @trieloff review on adobe#189)

@trieloff

…pets + a definition-vs-live checkpoint (per @trieloff) - Trim Step 3 to a concise consumer map (drop explanations the agent already knows). - Add executable snippets for Step 4 (sitemap vs index diff) and Step 5 (stale-entry HTTP check). - Add a Checkpoint between Steps 2 and 3 to reconcile the index definition against the live output before mapping consumers.

feat: Add query-index-optimizer skill for EDS content ops

d41bd96

focusgts requested a review from trieloff as a code owner June 15, 2026 14:41

focusgts temporarily deployed to eval June 15, 2026 14:41 — with GitHub Actions Inactive

focusgts mentioned this pull request Jun 15, 2026

feat: Add 4 performance and Core Web Vitals skills for EDS content ops #183

Closed

3 tasks

trieloff requested a review from dominique-pfister June 15, 2026 20:15

davefoxceo mentioned this pull request Jun 25, 2026

feat: Add cwv-optimizer skill for EDS content ops #186

Merged

1 task

dominique-pfister reviewed Jun 29, 2026

View reviewed changes

dominique-pfister requested changes Jun 29, 2026

View reviewed changes

focusgts temporarily deployed to eval June 29, 2026 15:44 — with GitHub Actions Inactive

style(query-index-optimizer): replace em-dashes with standard punctua…

cbfa302

…tion

focusgts temporarily deployed to eval July 7, 2026 08:49 — with GitHub Actions Inactive

trieloff mentioned this pull request Aug 21, 2026

ci(tessl-review): distinguish tooling failures from low scores #308

Merged

Merge upstream/main to bring the branch current and re-run CI against…

4c924d5

… the fixed fork-PR workflow (per @trieloff review on adobe#189)

focusgts had a problem deploying to eval August 21, 2026 13:56 — with GitHub Actions Error

focusgts requested a deployment to eval August 21, 2026 13:56 — with GitHub Actions Waiting

focusgts added a commit to focusgts/skills that referenced this pull request Aug 21, 2026

Merge upstream/main to bring the branch current and re-run CI against…

e5c2c78

… the fixed fork-PR workflow (per @trieloff review on adobe#189)

focusgts requested a deployment to eval August 21, 2026 14:09 — with GitHub Actions Waiting


		### Key Concepts

		- helix-query.yaml — Lives in the GitHub repo root. Defines which properties to index and how they are sourced (from metadata, headings, or content).


		## How the EDS Query Index Works

		The query index is the primary mechanism for blocks and components to discover and list content in an EDS site. It is configured via a `helix-query.yaml` file in the GitHub repository and served as JSON at `/query-index.json`.

Uh oh!

Conversation

focusgts commented Jun 15, 2026

Summary

Test plan

Uh oh!

trieloff commented Jun 15, 2026

Uh oh!

dominique-pfister Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

dominique-pfister Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

dominique-pfister Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

dominique-pfister Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dominique-pfister Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

dominique-pfister left a comment

Choose a reason for hiding this comment

Uh oh!

focusgts commented Jun 29, 2026

Uh oh!

focusgts commented Jun 29, 2026

Uh oh!

trieloff commented Jul 6, 2026

Uh oh!

focusgts commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

focusgts commented Aug 20, 2026

Uh oh!

trieloff commented Aug 21, 2026

Local review result

Uh oh!

trieloff commented Aug 21, 2026

Uh oh!

trieloff commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dominique-pfister Jun 29, 2026 •

edited

Loading

focusgts commented Aug 10, 2026 •

edited

Loading