@robot-inventor/agent-skills 0.0.0 → 0.7.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 roboin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 roboin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,31 +1,31 @@
-# Roboin Agent Skills
-
-My personal collection of Agent Skills.
-
-- [cleanup-changes](skills/cleanup-changes/SKILL.md): The skill to revert unnecessary changes and leave only essential changes.
-- [identify-search-maintenance](skills/identify-search-maintenance): The skill to identify web pages that are performing poorly in search results and require maintenance.
-- [prove-it-diagnostics](skills/prove-it-diagnostics/SKILL.md): The skill to fix bugs and improve performance by proving the root cause through minimal reproduction code or benchmarks, rather than relying on speculation based solely on reading the code.
-- [review-loop](skills/review-loop/SKILL.md): Thoroughly improve code quality by requesting a review from a sub-agent.
-- [simple-engineering](skills/simple-engineering/SKILL.md): A skill outlining the fundamental principles to keep in mind when writing or editing code.
-- [web-master](skills/web-master/SKILL.md): A skill outlining the fundamental principles to keep in mind when writing or editing web-related code.
-
-## Installation
-
-```bash
-# Install all skills
-npx skills add Robot-Inventor/agent-skills
-
-# Install a specific skill
-npx skills add Robot-Inventor/agent-skills --skill <skill-name>
-```
-
-## Plugins
-
-```bash
-# Codex
-codex plugin marketplace add Robot-Inventor/agent-skills
-codex plugin add agent-skills@robot-inventor
-
-# OpenCode
-opencode plugin @robot-inventor/agent-skills --global
-```
+# Roboin Agent Skills
+
+My personal collection of Agent Skills.
+
+- [cleanup-changes](skills/cleanup-changes/SKILL.md): The skill to revert unnecessary changes and leave only essential changes.
+- [identify-search-maintenance](skills/identify-search-maintenance): The skill to identify web pages that are performing poorly in search results and require maintenance.
+- [prove-it-diagnostics](skills/prove-it-diagnostics/SKILL.md): The skill to fix bugs and improve performance by proving the root cause through minimal reproduction code or benchmarks, rather than relying on speculation based solely on reading the code.
+- [review-loop](skills/review-loop/SKILL.md): Thoroughly improve code quality by requesting a review from a sub-agent.
+- [simple-engineering](skills/simple-engineering/SKILL.md): A skill outlining the fundamental principles to keep in mind when writing or editing code.
+- [web-master](skills/web-master/SKILL.md): A skill outlining the fundamental principles to keep in mind when writing or editing web-related code.
+
+## Installation
+
+```bash
+# Install all skills
+npx skills add Robot-Inventor/agent-skills
+
+# Install a specific skill
+npx skills add Robot-Inventor/agent-skills --skill <skill-name>
+```
+
+## Plugins
+
+```bash
+# Codex
+codex plugin marketplace add Robot-Inventor/agent-skills
+codex plugin add agent-skills@robot-inventor
+
+# OpenCode
+opencode plugin @robot-inventor/agent-skills --global
+```

package/package.json

@@ -1,33 +1,34 @@
-{
-  "name": "@robot-inventor/agent-skills",
-  "version": "0.0.0",
-  "description": "Roboin's personal collection of Agent Skills.",
-  "homepage": "https://github.com/Robot-Inventor/agent-skills#readme",
-  "bugs": {
-    "url": "https://github.com/Robot-Inventor/agent-skills/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Robot-Inventor/agent-skills.git"
-  },
-  "license": "MIT",
-  "author": "Robot-Inventor",
-  "type": "module",
-  "files": ["./plugin.json", "./skills/", "./scripts/opencode.ts"],
-  "publishConfig": {
-    "access": "public",
-    "provenance": false
-  },
-  "scripts": {
-    "ci:version": "changeset version && bun ./scripts/syncVersion.ts && git add .",
-    "ci:publish": "changeset publish"
-  },
-  "devDependencies": {
-    "@changesets/changelog-github": "^1.0.0",
-    "@changesets/cli": "^3.0.0",
-    "@opencode-ai/plugin": "^1.18.18",
-    "@robot-inventor/tsconfig-base": "^7.1.0",
-    "@types/bun": "^1.3.14",
-    "@types/node": "^26.2.0"
-  }
-}
+{
+  "name": "@robot-inventor/agent-skills",
+  "version": "0.7.1",
+  "description": "Roboin's personal collection of Agent Skills.",
+  "homepage": "https://github.com/Robot-Inventor/agent-skills#readme",
+  "bugs": {
+    "url": "https://github.com/Robot-Inventor/agent-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Robot-Inventor/agent-skills.git"
+  },
+  "license": "MIT",
+  "author": "Robot-Inventor",
+  "type": "module",
+  "main": "./scripts/opencode.ts",
+  "files": ["./plugin.json", "./skills/", "./scripts/"],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "ci:version": "changeset version && bun ./scripts/syncVersion.ts && git add .",
+    "ci:publish": "changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.0",
+    "@opencode-ai/plugin": "^1.18.18",
+    "@robot-inventor/tsconfig-base": "^7.1.0",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.2.0"
+  }
+}

package/plugin.json

@@ -1,12 +1,12 @@
-{
-    "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
-    "name": "roboin-agent-skills",
-    "version": "0.7.0",
-    "description": "My personal collection of Agent Skills.",
-    "author": {
-        "name": "Robot-Inventor",
-        "url": "https://roboin.io/"
-    },
-    "repository": "https://github.com/Robot-Inventor/agent-skills",
-    "license": "MIT"
+{
+    "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+    "name": "agent-skills",
+    "version": "0.7.1",
+    "description": "My personal collection of Agent Skills.",
+    "author": {
+        "name": "Robot-Inventor",
+        "url": "https://roboin.io/"
+    },
+    "repository": "https://github.com/Robot-Inventor/agent-skills",
+    "license": "MIT"
 }

package/scripts/codex.ts

@@ -0,0 +1,35 @@
+import { exists, readFile } from "node:fs/promises";
+import { dirname, join, parse } from "node:path";
+import { SKILLS } from "./skills";
+
+const main = async () => {
+    let input = "";
+    process.stdin.setEncoding("utf8");
+    for await (const chunk of process.stdin) {
+        input += chunk;
+    }
+
+    const { cwd } = JSON.parse(input) as { cwd: string };
+
+    const isWebProject = await exists(join(cwd, "package.json"));
+    const skills = isWebProject ? SKILLS.web : SKILLS.nonWeb;
+
+    const pluginRoot = process.env.PLUGIN_ROOT;
+    if (!pluginRoot) {
+        throw new Error("PLUGIN_ROOT is not set");
+    }
+
+    const skillContentPromises = skills.map(async (skill) => {
+        const skillPath = join(pluginRoot, "skills", skill, "SKILL.md");
+        const skillContent = await readFile(skillPath, "utf8");
+
+        return [`<forced-skill name="${skill}">`, skillContent, "</forced-skill>"].join("\n");
+    });
+
+    const skillContents = await Promise.all(skillContentPromises);
+    const content = skillContents.join("\n\n");
+
+    process.stdout.write(content);
+};
+
+await main();

package/scripts/opencode.ts

@@ -1,26 +1,26 @@
-import type { Plugin } from "@opencode-ai/plugin";
-import { SKILLS } from "./skills";
-import { exists } from "node:fs/promises";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const plugin: Plugin = async ({ project, directory }) => {
-    const isWebProject = await exists(join(directory, "package.json"));
-    const skills = isWebProject ? SKILLS.web : SKILLS.nonWeb;
-
-    return {
-        config: async (config) => {
-            config.instructions ??= [];
-
-            for (const skill of skills) {
-                const path = fileURLToPath(new URL(`../skills/${skill}/SKILL.md`, import.meta.url));
-
-                if (!config.instructions.includes(path)) {
-                    config.instructions.push(path);
-                }
-            }
-        }
-    };
-};
-
-export { plugin };
+import type { Plugin } from "@opencode-ai/plugin";
+import { SKILLS } from "./skills";
+import { exists } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const plugin: Plugin = async ({ project, directory }) => {
+    const isWebProject = await exists(join(directory, "package.json"));
+    const skills = isWebProject ? SKILLS.web : SKILLS.nonWeb;
+
+    return {
+        config: async (config) => {
+            config.instructions ??= [];
+
+            for (const skill of skills) {
+                const path = fileURLToPath(new URL(`../skills/${skill}/SKILL.md`, import.meta.url));
+
+                if (!config.instructions.includes(path)) {
+                    config.instructions.push(path);
+                }
+            }
+        }
+    };
+};
+
+export { plugin };

package/scripts/skills.ts

@@ -0,0 +1,6 @@
+const SKILLS = {
+    web: ["review-loop", "simple-engineering", "web-master"],
+    nonWeb: ["review-loop", "simple-engineering"]
+} as const;
+
+export { SKILLS };

package/scripts/syncVersion.ts

@@ -0,0 +1,10 @@
+import fs from "fs/promises";
+import packageJson from "../package.json";
+import pluginJson from "../plugin.json";
+
+const main = async () => {
+  pluginJson.version = packageJson.version;
+  await fs.writeFile("plugin.json", JSON.stringify(pluginJson, null, 4));
+};
+
+await main();

package/skills/cleanup-changes/SKILL.md

@@ -1,33 +1,33 @@
----
-name: cleanup-changes
-description: The skill to revert unnecessary changes and leave only essential changes when a user requests a cleanup of changes, or before committing and creating a pull request.
-license: MIT
-metadata:
-  author: Robot-Inventor
----
-
-# Cleanup Changes Skill
-
-Both humans and agents typically go through a trial-and-error process when writing code, making numerous changes (including non-essential and unnecessary ones) to achieve their final goals. However, non-essential and unnecessary changes resulting from this trial-and-error process should not be included in the final code. Changes should be reviewed as needed, and unnecessary changes should be reversed to focus only on essential ones.
-
-## When to apply
-
-You should perform this skill when a user requests a cleanup of changes, or before creating a commit or pull request.
-
-## Steps
-
-The following is the core of this skill; please follow the specified steps. Do not change the Git staging state unless explicitly instructed to do so by the user. Users may have staged their changes as a snapshot of the code in its last expected state.
-
-### 1. Looking back on the trial-and-error process
-
-Reflect on the trial-and-error process of the task and distinguish between changes that were essentially necessary and changes that, despite being tried, ultimately proved ineffective and unnecessary.
-
-You shouldn't make assumptions about whether a change is essentially necessary. For example, when fixing a bug, review the changes made when the bug was finally fixed, understand the essential and root cause of the bug, and then, based on that, determine whether each change is essentially necessary.
-
-When determining whether each change is necessary, pay particular attention to bugs caused by multiple factors. Bugs can be caused by a single, simple cause, or by multiple factors. If it's caused by a single, simple cause, the last change made when the bug is fixed may be sufficient, and previous changes may be unnecessary. If it's a bug caused by multiple factors, the last change alone may not be enough, and some of the changes made during the trial-and-error process leading up to it may also be necessary. Carefully consider the underlying cause of the bug, including whether it's due to a single cause or multiple factors, and then determine which changes are necessary and which are not.
-
-### 2. Undo unnecessary changes
-
-Revert any changes you determined were unnecessary in the previous step, leaving only the essential changes.
-
-However, even if a change isn't strictly necessary, minor corrections to typos around the current change or small refactorings are acceptable. Generally, in coding, correcting typos found around a change or making small refactorings related to the current change are generally tolerated, even if they aren't strictly necessary.
+---
+name: cleanup-changes
+description: The skill to revert unnecessary changes and leave only essential changes when a user requests a cleanup of changes, or before committing and creating a pull request.
+license: MIT
+metadata:
+  author: Robot-Inventor
+---
+
+# Cleanup Changes Skill
+
+Both humans and agents typically go through a trial-and-error process when writing code, making numerous changes (including non-essential and unnecessary ones) to achieve their final goals. However, non-essential and unnecessary changes resulting from this trial-and-error process should not be included in the final code. Changes should be reviewed as needed, and unnecessary changes should be reversed to focus only on essential ones.
+
+## When to apply
+
+You should perform this skill when a user requests a cleanup of changes, or before creating a commit or pull request.
+
+## Steps
+
+The following is the core of this skill; please follow the specified steps. Do not change the Git staging state unless explicitly instructed to do so by the user. Users may have staged their changes as a snapshot of the code in its last expected state.
+
+### 1. Looking back on the trial-and-error process
+
+Reflect on the trial-and-error process of the task and distinguish between changes that were essentially necessary and changes that, despite being tried, ultimately proved ineffective and unnecessary.
+
+You shouldn't make assumptions about whether a change is essentially necessary. For example, when fixing a bug, review the changes made when the bug was finally fixed, understand the essential and root cause of the bug, and then, based on that, determine whether each change is essentially necessary.
+
+When determining whether each change is necessary, pay particular attention to bugs caused by multiple factors. Bugs can be caused by a single, simple cause, or by multiple factors. If it's caused by a single, simple cause, the last change made when the bug is fixed may be sufficient, and previous changes may be unnecessary. If it's a bug caused by multiple factors, the last change alone may not be enough, and some of the changes made during the trial-and-error process leading up to it may also be necessary. Carefully consider the underlying cause of the bug, including whether it's due to a single cause or multiple factors, and then determine which changes are necessary and which are not.
+
+### 2. Undo unnecessary changes
+
+Revert any changes you determined were unnecessary in the previous step, leaving only the essential changes.
+
+However, even if a change isn't strictly necessary, minor corrections to typos around the current change or small refactorings are acceptable. Generally, in coding, correcting typos found around a change or making small refactorings related to the current change are generally tolerated, even if they aren't strictly necessary.

package/skills/identify-search-maintenance/SKILL.md

@@ -1,78 +1,78 @@
----
-name: identify-search-maintenance
-description: Identify and diagnose organic-search articles that need maintenance. Use when asked to find pages whose organic traffic declined mainly from ranking loss rather than search-demand decline, analyze Search Console or GA4 data across recent and year-over-year periods, prioritize a maintenance backlog, or compare target pages with current Google results. Do not use this skill to edit article content.
----
-
-# Identify Search Maintenance
-
-Find pages that merit search-maintenance work, with evidence that separates rank-driven losses from changes in demand. The deliverable is a ranked investigation backlog and diagnosis; it is never an article rewrite or publishing task.
-
-## Scope and guardrails
-
-- Confirm the property, traffic channel, dates, locale/device, and whether Google must be inspected through the user's signed-in Chrome session.
-- Use both recent comparison (normally the latest 3 months vs. the preceding 3 months) and a year-over-year comparison (normally the same recent 3 months one year earlier). End periods on the latest Search Console date that is complete enough to compare, use equal day counts and comparable weekday mix, and state any unavailable baseline as `N/A`, never as zero.
-- Fix the Search Console search type, country, device, property scope, canonical-URL handling, and any brand-query exclusion across each comparison. Record GA4 timezone, Organic Search channel definition, and landing-page URL normalization.
-- Treat a page as a candidate only after checking page-level **and** query-level Search Console data. GA4 is corroborating traffic evidence, not a substitute for query and rank data.
-- Do not attribute a loss to rankings from clicks alone. URL-filtered and property-wide Search Console impressions are affected by the site's own visibility and are not standalone demand measures. Check an independent demand proxy (for example Google Trends for the query/topic, Keyword Planner where available, or a documented market-data source), then use property-wide query data only as corroboration. Also check URL/query rank changes, cannibalization, and live SERP composition.
-- Do not alter CMS content, metadata, internal links, or publish settings. If the user asks for changes, finish this investigation first and obtain a separate article-update scope.
-
-## Workflow
-
-### 1. Collect comparable evidence
-
-1. Export Search Console performance by **page** for the two period pairs. Prefer an export/CSV over manually paging a truncated table.
-2. Retain clicks, impressions, CTR, and average position for each period. Record filters, property, and export dates.
-3. Obtain GA4 organic-search landing-page sessions or views for the same dates when available. Note that GA4 and Search Console count different things.
-4. Normalize both the recent-pair and year-over-year page exports to the columns in [selection-rubric.md](references/selection-rubric.md). Run the bundled filter on each, take the union of the two candidate lists, and label the comparison(s) that surfaced each URL. A page that only passes one comparison still needs the full evidence checks in both.
-
-```powershell
-python "<skill-directory>/scripts/select_rank_led_candidates.py" normalized-pages.csv --format markdown
-```
-
-Replace `<skill-directory>` with the directory containing this `SKILL.md`. Use the script to screen candidates, not to make the final decision. Tune its thresholds only if the report explains why.
-
-### 2. Separate causes before selecting pages
-
-Classify each materially declining page into one of these mutually exclusive buckets:
-
-| Bucket                               | Evidence                                                                                 | Action                                                                                 |
-| ------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| Rank-led maintenance candidate       | Clicks materially down; impressions broadly stable; average position/query ranks worsen  | Investigate and prioritize                                                             |
-| Demand/obsolescence decline          | Impressions and clicks fall together, or the task/query has ended                        | Exclude from the rank-led list                                                         |
-| CTR/SERP change                      | Position broadly stable but CTR falls; SERP features or title/snippet changes explain it | Keep separate; do not call it rank-led                                                 |
-| Technical/indexing issue             | Indexing, canonical, rendering, or availability evidence                                 | Escalate separately                                                                    |
-| Cannibalization/internal competition | Another site URL gained the same query or intent                                         | Exclude from this content-maintenance list; route for consolidation/targeting decision |
-| Insufficient evidence                | Low volume or no comparable baseline                                                     | Do not force into the top 10                                                           |
-
-For every selected URL, verify at least three previously valuable declined queries. For each query, collect three views with identical search type/country/device/date filters: (a) the target URL's query metrics and position, (b) the **whole property** query metrics without a page filter, and (c) an independent demand proxy. Treat (c) as the demand evidence; use (b) only to understand the site's overall visibility. Use year-over-year data to catch longer-running changes. Check whether another URL in the property gained the same query; classify confirmed cannibalization in its own exclusion bucket. If the query mix changed, say so.
-
-Before retaining a content-maintenance candidate, perform a minimum health check: URL Inspection/index status, user-selected canonical, HTTP availability, and rendered-page accessibility. Classify a failing page as a technical/indexing issue instead of diagnosing an editorial gap.
-
-### 3. Diagnose each selected page in Google
-
-When the user specifies Chrome or Google, use the Chrome browser, not a general web-search backend. For each selected URL:
-
-1. Search at least three declined, historically valuable queries in Google, using the required locale/device context where possible.
-2. Capture the target URL's visible rank or absence, the top competing URLs, and material SERP features (AI Overview, official result, video carousel, PAA, news, forums, etc.). Use fresh tabs and do not change account or site settings.
-3. Compare the target and the leading pages on search intent, freshness, direct answer quality, task completion, factual completeness, first-party evidence, visual/media support, structure, and trust signals. Base observations on actual page content; distinguish observed facts from inference.
-4. Identify the gap to investigate, not the edit itself. Examples: outdated UI steps, missing current constraints, poor intent match, weak original evidence, or a SERP now dominated by official sources.
-
-If parallel agents are available, assign no more than two pages to each agent. Require each agent to return the period metrics, three or more queries, Google competitors, SERP features, observed content gaps, exclusions, and source URLs. Consolidate only after all agents return evidence.
-
-### 4. Produce the maintenance report
-
-Create or append to `report.md`; preserve earlier findings unless the user asks to replace them. Use this structure:
-
-1. Scope, dates, data sources, filters, and limitations.
-2. Selection method and explicit rank-led thresholds.
-3. A prioritized table of up to the requested number of rank-led pages (default 10): URL, recent metrics, year-over-year metrics, property-wide query-demand evidence, ranking evidence, priority, and confidence. If fewer pages meet the evidence threshold, report fewer and explain the shortfall.
-4. Per-page diagnosis: three or more declined queries, current Google competitors/SERP observations, and content gaps to investigate.
-5. Excluded near-misses with the evidence for demand decline, obsolete intent, CTR-only loss, technical issue, cannibalization, or insufficient data.
-6. A separate follow-up queue for work that needs a technical or editorial decision.
-
-Before delivery, verify that every page in the final rank-led list has stable-enough independent demand evidence, a documented query-level rank deterioration, and a passing health check. Never fill a quota with demand-led losses.
-
-## Resources
-
-- [selection-rubric.md](references/selection-rubric.md): normalization schema, default thresholds, and report checklist.
-- `scripts/select_rank_led_candidates.py`: deterministic first-pass filter for normalized Search Console page exports.
+---
+name: identify-search-maintenance
+description: Identify and diagnose organic-search articles that need maintenance. Use when asked to find pages whose organic traffic declined mainly from ranking loss rather than search-demand decline, analyze Search Console or GA4 data across recent and year-over-year periods, prioritize a maintenance backlog, or compare target pages with current Google results. Do not use this skill to edit article content.
+---
+
+# Identify Search Maintenance
+
+Find pages that merit search-maintenance work, with evidence that separates rank-driven losses from changes in demand. The deliverable is a ranked investigation backlog and diagnosis; it is never an article rewrite or publishing task.
+
+## Scope and guardrails
+
+- Confirm the property, traffic channel, dates, locale/device, and whether Google must be inspected through the user's signed-in Chrome session.
+- Use both recent comparison (normally the latest 3 months vs. the preceding 3 months) and a year-over-year comparison (normally the same recent 3 months one year earlier). End periods on the latest Search Console date that is complete enough to compare, use equal day counts and comparable weekday mix, and state any unavailable baseline as `N/A`, never as zero.
+- Fix the Search Console search type, country, device, property scope, canonical-URL handling, and any brand-query exclusion across each comparison. Record GA4 timezone, Organic Search channel definition, and landing-page URL normalization.
+- Treat a page as a candidate only after checking page-level **and** query-level Search Console data. GA4 is corroborating traffic evidence, not a substitute for query and rank data.
+- Do not attribute a loss to rankings from clicks alone. URL-filtered and property-wide Search Console impressions are affected by the site's own visibility and are not standalone demand measures. Check an independent demand proxy (for example Google Trends for the query/topic, Keyword Planner where available, or a documented market-data source), then use property-wide query data only as corroboration. Also check URL/query rank changes, cannibalization, and live SERP composition.
+- Do not alter CMS content, metadata, internal links, or publish settings. If the user asks for changes, finish this investigation first and obtain a separate article-update scope.
+
+## Workflow
+
+### 1. Collect comparable evidence
+
+1. Export Search Console performance by **page** for the two period pairs. Prefer an export/CSV over manually paging a truncated table.
+2. Retain clicks, impressions, CTR, and average position for each period. Record filters, property, and export dates.
+3. Obtain GA4 organic-search landing-page sessions or views for the same dates when available. Note that GA4 and Search Console count different things.
+4. Normalize both the recent-pair and year-over-year page exports to the columns in [selection-rubric.md](references/selection-rubric.md). Run the bundled filter on each, take the union of the two candidate lists, and label the comparison(s) that surfaced each URL. A page that only passes one comparison still needs the full evidence checks in both.
+
+```powershell
+python "<skill-directory>/scripts/select_rank_led_candidates.py" normalized-pages.csv --format markdown
+```
+
+Replace `<skill-directory>` with the directory containing this `SKILL.md`. Use the script to screen candidates, not to make the final decision. Tune its thresholds only if the report explains why.
+
+### 2. Separate causes before selecting pages
+
+Classify each materially declining page into one of these mutually exclusive buckets:
+
+| Bucket                               | Evidence                                                                                 | Action                                                                                 |
+| ------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Rank-led maintenance candidate       | Clicks materially down; impressions broadly stable; average position/query ranks worsen  | Investigate and prioritize                                                             |
+| Demand/obsolescence decline          | Impressions and clicks fall together, or the task/query has ended                        | Exclude from the rank-led list                                                         |
+| CTR/SERP change                      | Position broadly stable but CTR falls; SERP features or title/snippet changes explain it | Keep separate; do not call it rank-led                                                 |
+| Technical/indexing issue             | Indexing, canonical, rendering, or availability evidence                                 | Escalate separately                                                                    |
+| Cannibalization/internal competition | Another site URL gained the same query or intent                                         | Exclude from this content-maintenance list; route for consolidation/targeting decision |
+| Insufficient evidence                | Low volume or no comparable baseline                                                     | Do not force into the top 10                                                           |
+
+For every selected URL, verify at least three previously valuable declined queries. For each query, collect three views with identical search type/country/device/date filters: (a) the target URL's query metrics and position, (b) the **whole property** query metrics without a page filter, and (c) an independent demand proxy. Treat (c) as the demand evidence; use (b) only to understand the site's overall visibility. Use year-over-year data to catch longer-running changes. Check whether another URL in the property gained the same query; classify confirmed cannibalization in its own exclusion bucket. If the query mix changed, say so.
+
+Before retaining a content-maintenance candidate, perform a minimum health check: URL Inspection/index status, user-selected canonical, HTTP availability, and rendered-page accessibility. Classify a failing page as a technical/indexing issue instead of diagnosing an editorial gap.
+
+### 3. Diagnose each selected page in Google
+
+When the user specifies Chrome or Google, use the Chrome browser, not a general web-search backend. For each selected URL:
+
+1. Search at least three declined, historically valuable queries in Google, using the required locale/device context where possible.
+2. Capture the target URL's visible rank or absence, the top competing URLs, and material SERP features (AI Overview, official result, video carousel, PAA, news, forums, etc.). Use fresh tabs and do not change account or site settings.
+3. Compare the target and the leading pages on search intent, freshness, direct answer quality, task completion, factual completeness, first-party evidence, visual/media support, structure, and trust signals. Base observations on actual page content; distinguish observed facts from inference.
+4. Identify the gap to investigate, not the edit itself. Examples: outdated UI steps, missing current constraints, poor intent match, weak original evidence, or a SERP now dominated by official sources.
+
+If parallel agents are available, assign no more than two pages to each agent. Require each agent to return the period metrics, three or more queries, Google competitors, SERP features, observed content gaps, exclusions, and source URLs. Consolidate only after all agents return evidence.
+
+### 4. Produce the maintenance report
+
+Create or append to `report.md`; preserve earlier findings unless the user asks to replace them. Use this structure:
+
+1. Scope, dates, data sources, filters, and limitations.
+2. Selection method and explicit rank-led thresholds.
+3. A prioritized table of up to the requested number of rank-led pages (default 10): URL, recent metrics, year-over-year metrics, property-wide query-demand evidence, ranking evidence, priority, and confidence. If fewer pages meet the evidence threshold, report fewer and explain the shortfall.
+4. Per-page diagnosis: three or more declined queries, current Google competitors/SERP observations, and content gaps to investigate.
+5. Excluded near-misses with the evidence for demand decline, obsolete intent, CTR-only loss, technical issue, cannibalization, or insufficient data.
+6. A separate follow-up queue for work that needs a technical or editorial decision.
+
+Before delivery, verify that every page in the final rank-led list has stable-enough independent demand evidence, a documented query-level rank deterioration, and a passing health check. Never fill a quota with demand-led losses.
+
+## Resources
+
+- [selection-rubric.md](references/selection-rubric.md): normalization schema, default thresholds, and report checklist.
+- `scripts/select_rank_led_candidates.py`: deterministic first-pass filter for normalized Search Console page exports.