@raishin/vanguard-frontier-agentic 1.7.1 → 1.9.0

package/scripts/generate-plugin-manifest.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * Generate .claude-plugin/plugin.json from catalog/agents.json.
+ *
+ * The Claude Code plugin spec lets a manifest declare its agents via an
+ * explicit array of file paths (see code.claude.com/docs/en/plugins-reference,
+ * field `agents`). The repo's agents live at
+ *   agents/<provider>/<agent>/harnesses/claude-code.agent.md
+ * which is one nesting level deeper than the conventional flat
+ *   agents/<agent>.md
+ * Rather than restructuring the catalog (which would break the multi-harness
+ * design and the npm package layout), this script enumerates every
+ * claude-code adapter file and writes it into plugin.json's `agents` array.
+ *
+ * Output is sorted and deterministic so the manifest is reproducible across
+ * runs and reviewable in PR diffs.
+ *
+ * Mode:
+ *   --check  exit 1 if the on-disk manifest does not match the generated one
+ *   (default) overwrite the on-disk manifest
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const catalogPath = join(repoRoot, "catalog", "agents.json");
+const skillManifestPath = join(repoRoot, "catalog", "skill-manifest.json");
+const manifestPath = join(repoRoot, ".claude-plugin", "plugin.json");
+const pkgPath = join(repoRoot, "package.json");
+
+const check = process.argv.includes("--check");
+
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
+
+function manifestPathForAdapter(entry, adapter) {
+  // Note 1: Treat catalog paths as untrusted input. Even though this repo
+  // owns catalog/agents.json, release tooling should fail closed because a
+  // future PR can change metadata without touching the generator itself.
+  if (
+    typeof adapter !== "string"
+    || adapter.trim() === ""
+    || isAbsolute(adapter)
+  ) {
+    throw new Error(
+      `Agent ${entry.id} has an invalid claude-code harness path: ${adapter}`,
+    );
+  }
+  // Note 2: Joining against repoRoot normalizes ordinary relative paths, but
+  // it does not by itself prove containment. For example, "../x" resolves
+  // successfully; the relative() check below is what detects the escape.
+  const resolved = join(repoRoot, adapter);
+  const rel = relative(repoRoot, resolved);
+  // Note 3: A path is inside repoRoot only when the normalized relative path
+  // is not "..", does not start with "../", and is not absolute. This mirrors
+  // the defensive pattern used by the export CLI for install destinations.
+  if (rel === "" || rel.startsWith(`..${sep}`) || rel === ".." || isAbsolute(rel)) {
+    throw new Error(
+      `Agent ${entry.id} claude-code harness path escapes the repository: ${adapter}`,
+    );
+  }
+  // Note 4: Plugin manifests use POSIX-style paths even when generated on
+  // Windows, so split/join converts platform separators into stable JSON.
+  return `./${rel.split(sep).join("/")}`;
+}
+
+const agentEntries = catalog
+  .filter((entry) => entry.type === "agent")
+  .filter((entry) => Array.isArray(entry.harnesses) && entry.harnesses.includes("claude-code"))
+  .map((entry) => {
+    const adapter = entry.harness_variants?.["claude-code"]
+      ?? `${entry.path}/harnesses/claude-code.agent.md`;
+    return manifestPathForAdapter(entry, adapter);
+  })
+  .sort();
+
+// Validate every adapter file actually exists. A missing adapter would let
+// Claude Code register a phantom agent that errors on first invocation.
+const missing = agentEntries.filter((p) => !existsSync(join(repoRoot, p)));
+if (missing.length > 0) {
+  console.error("ERROR: plugin manifest references files that do not exist:");
+  missing.forEach((p) => console.error("  " + p));
+  process.exit(2);
+}
+
+// Skills are nested under skills/<provider>/<skill>/SKILL.md. Claude Code's
+// plugin loader expects skills/<skill>/SKILL.md (one level less). Until
+// the skill tree is flattened or Claude Code adds nested discovery, we
+// omit `skills` from the manifest to avoid silently shipping zero skills
+// under a misleading declaration. The catalog/skill-manifest.json remains
+// authoritative for the npm install path.
+const skillCount = existsSync(skillManifestPath)
+  ? JSON.parse(readFileSync(skillManifestPath, "utf8")).length ?? 0
+  : 0;
+
+const manifest = {
+  name: "vanguard-frontier-agentic",
+  version: pkg.version,
+  description: pkg.description,
+  author: {
+    name: "Raishin",
+    url: "https://github.com/Raishin",
+  },
+  homepage: "https://github.com/Raishin/vanguard-frontier-agentic",
+  repository: "https://github.com/Raishin/vanguard-frontier-agentic",
+  license: pkg.license,
+  keywords: [
+    "agentic",
+    "agents",
+    "marketplace",
+    "cloud",
+    "aws",
+    "azure",
+    "gcp",
+    "oci",
+    "alibaba",
+    "huawei",
+    "kubernetes",
+    "terraform",
+    "zero-trust",
+    "compliance",
+    "claude-code",
+  ],
+  agents: agentEntries,
+};
+
+const next = JSON.stringify(manifest, null, 2) + "\n";
+
+if (check) {
+  if (!existsSync(manifestPath)) {
+    console.error(`ERROR: ${manifestPath} is missing; run npm run plugin-manifest:write`);
+    process.exit(1);
+  }
+  const current = readFileSync(manifestPath, "utf8");
+  if (current !== next) {
+    console.error(
+      `ERROR: ${relative(repoRoot, manifestPath)} is stale (${agentEntries.length} agents in catalog, manifest is out of sync); run npm run plugin-manifest:write`,
+    );
+    process.exit(1);
+  }
+  console.log(
+    `OK: plugin manifest is in sync (${agentEntries.length} agents, ${skillCount} skills tracked in catalog/skill-manifest.json)`,
+  );
+} else {
+  writeFileSync(manifestPath, next);
+  console.log(
+    `OK: wrote ${relative(repoRoot, manifestPath)} (${agentEntries.length} agents)`,
+  );
+}

package/scripts/release-prepare.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Semantic-release prepare-step bridge.
+ *
+ * Runs AFTER `@semantic-release/npm` writes the bumped version to
+ * `package.json`, and BEFORE `@semantic-release/npm` packs+publishes the
+ * tarball. Synchronizes every published artifact whose content depends on
+ * `package.json.version` or on file hashes that include `package.json`:
+ *
+ *   1. .claude-plugin/plugin.json         — version-parity (validate:plugin-manifest)
+ *   2. .cursor-plugin/plugin.json         — version-parity (validate:multi-harness-marketplace)
+ *   3. plugins/vanguard-frontier-agentic/.codex-plugin/plugin.json
+ *                                         — version-parity (validate:codex-marketplace)
+ *   4. catalog/asset-integrity.json       — includes package.json sha256
+ *
+ * Without this step the released tarball would ship plugin manifests whose
+ * version diverges from `package.json` (breaks every harness's version-parity
+ * gate) and an asset-integrity manifest whose package.json hash no longer
+ * matches the released tree (breaks downstream attestation verification).
+ *
+ * Idempotent: re-running on an already-synced tree is a no-op.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REPO = dirname(dirname(fileURLToPath(import.meta.url)));
+const PKG = JSON.parse(readFileSync(join(REPO, "package.json"), "utf8"));
+const NEXT_VERSION = process.argv[2] || PKG.version;
+
+// Defense-in-depth: reject non-semver version strings before they are
+// written into plugin JSON files. The primary caller (@semantic-release/exec)
+// always supplies a strict semver string, but manual invocations have no
+// other guard. JSON.stringify escapes the value safely, so there is no
+// injection risk, but a bogus string would silently corrupt plugin manifests.
+if (!/^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/.test(NEXT_VERSION)) {
+  console.error(`[release-prepare] Refusing unsafe version string: ${NEXT_VERSION}`);
+  process.exit(1);
+}
+
+const VERSION_PINNED_PLUGINS = [
+  ".claude-plugin/plugin.json",
+  ".cursor-plugin/plugin.json",
+  "plugins/vanguard-frontier-agentic/.codex-plugin/plugin.json",
+];
+
+function syncPluginVersion(relPath) {
+  const abs = join(REPO, relPath);
+  const data = JSON.parse(readFileSync(abs, "utf8"));
+  if (data.version === NEXT_VERSION) {
+    return false;
+  }
+  data.version = NEXT_VERSION;
+  writeFileSync(abs, JSON.stringify(data, null, 2) + "\n", "utf8");
+  return true;
+}
+
+function regenerate(cmd, args) {
+  const result = spawnSync(cmd, args, { cwd: REPO, stdio: "inherit" });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}
+
+console.log(`[release-prepare] syncing artifacts to version ${NEXT_VERSION}`);
+
+let touched = 0;
+for (const rel of VERSION_PINNED_PLUGINS) {
+  if (syncPluginVersion(rel)) {
+    console.log(`[release-prepare] updated ${rel}`);
+    touched += 1;
+  }
+}
+
+// Re-run the Claude Code + Cursor manifest generators so any other
+// catalog-derived fields (agents[] list, etc.) stay in sync alongside
+// the version bump.
+regenerate("node", ["scripts/generate-plugin-manifest.mjs"]);
+regenerate("node", ["scripts/generate-cursor-plugin.mjs"]);
+
+// Regenerate the cross-asset integrity manifest LAST so it covers the
+// freshly bumped package.json plus the freshly synchronized plugin
+// manifests.
+regenerate("python3", ["tests/validate-asset-integrity.py", "--write"]);
+
+console.log(`[release-prepare] done (touched ${touched} plugin manifests)`);

package/skills/claude/README.md

@@ -0,0 +1,7 @@
+# Claude Skills
+
+Skills designed to enhance Claude's capabilities in code education, analysis, and development workflows.
+
+## Skills Included
+
+- `add-educational-comments` — Transform code files into effective learning resources by adding contextual educational comments tailored to learner knowledge levels and educational goals.

package/skills/claude/add-educational-comments/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: add-educational-comments
+description: Add educational comments to code files to transform them into effective learning resources. Explains the "why" behind syntax, idioms, and design choices, aligned with the learner's knowledge level and educational goals.
+allowed-tools: Read Write Edit Bash
+metadata:
+  author: "Claude"
+  version: "1.0.0"
+  updated: "2026-05-11"
+  category: delivery
+  lifecycle: stable
+  execution_tier: local
+  output_format: annotated-code
+  eval_fixtures: tests/fixtures/add-educational-comments/
+---
+
+# Add Educational Comments
+
+Add educational comments to code files so they become effective learning resources. When no file is provided, request one and offer a numbered list of close matches for quick selection.
+
+## Role
+
+You are an expert educator and technical writer. You can explain programming topics to beginners, intermediate learners, and advanced practitioners. You adapt tone and detail to match the user's configured knowledge levels while keeping guidance encouraging and instructional.
+
+- Provide foundational explanations for beginners
+- Add practical insights and best practices for intermediate users
+- Offer deeper context (performance, architecture, language internals) for advanced users
+- Suggest improvements only when they meaningfully support understanding
+- Always obey the **Educational Commenting Rules**
+
+## Objectives
+
+1. Transform the provided file by adding educational comments aligned with the configuration.
+2. Maintain the file's structure, encoding, and build correctness.
+3. Increase the total line count by **125%** using educational comments only (up to 400 new lines). For files already processed with this prompt, update existing notes instead of reapplying the 125% rule.
+
+### Line Count Guidance
+
+- Default: add lines so the file reaches 125% of its original length.
+- Hard limit: never add more than 400 educational comment lines.
+- Large files: when the file exceeds 1,000 lines, aim for no more than 300 educational comment lines.
+- Previously processed files: revise and improve current comments; do not chase the 125% increase again.
+
+## Educational Commenting Rules
+
+### Encoding and Formatting
+
+- Determine the file's encoding before editing and keep it unchanged.
+- Use only characters available on a standard QWERTY keyboard.
+- Do not insert emojis or other special symbols.
+- Preserve the original end-of-line style (LF or CRLF).
+- Keep single-line comments on a single line.
+- Maintain the indentation style required by the language (Python, Haskell, F#, Nim, Cobra, YAML, Makefiles, etc.).
+- When instructed with `Line Number Referencing = yes`, prefix each new comment with `Note <number>` (e.g., `Note 1`).
+
+### Content Expectations
+
+- Focus on lines and blocks that best illustrate language or platform concepts.
+- Explain the "why" behind syntax, idioms, and design choices.
+- Reinforce previous concepts only when it improves comprehension (`Repetitiveness`).
+- Highlight potential improvements gently and only when they serve an educational purpose.
+- If `Line Number Referencing = yes`, use note numbers to connect related explanations.
+
+### Safety and Compliance
+
+- Do not alter namespaces, imports, module declarations, or encoding headers in a way that breaks execution.
+- Avoid introducing syntax errors (for example, Python encoding errors per [PEP 263](https://peps.python.org/pep-0263/)).
+- Input data as if typed on the user's keyboard.
+
+## Workflow
+
+1. **Confirm Inputs** – Ensure at least one target file is provided. If missing, respond with: `Please provide a file or files to add educational comments to. Preferably as chat variable or attached context.`
+2. **Identify File(s)** – If multiple matches exist, present an ordered list so the user can choose by number or name.
+3. **Review Configuration** – Combine the prompt defaults with user-specified values. Interpret obvious typos (e.g., `Line Number`) using context.
+4. **Plan Comments** – Decide which sections of the code best support the configured learning goals.
+5. **Add Comments** – Apply educational comments following the configured detail, repetitiveness, and knowledge levels. Respect indentation and language syntax.
+6. **Validate** – Confirm formatting, encoding, and syntax remain intact. Ensure the 125% rule and line limits are satisfied.
+
+## Configuration Reference
+
+### Properties
+
+- **Numeric Scale**: `1-3`
+- **Numeric Sequence**: `ordered` (higher numbers represent higher knowledge or intensity)
+
+### Parameters
+
+- **File Name** (required): Target file(s) for commenting.
+- **Comment Detail** (`1-3`): Depth of each explanation (default `2`).
+- **Repetitiveness** (`1-3`): Frequency of revisiting similar concepts (default `2`).
+- **Educational Nature**: Domain focus (default `Computer Science`).
+- **User Knowledge** (`1-3`): General CS/SE familiarity (default `2`).
+- **Educational Level** (`1-3`): Familiarity with the specific language or framework (default `1`).
+- **Line Number Referencing** (`yes/no`): Prepend comments with note numbers when `yes` (default `yes`).
+- **Nest Comments** (`yes/no`): Whether to indent comments inside code blocks (default `yes`).
+- **Fetch List**: Optional URLs for authoritative references.
+
+If a configurable element is missing, use the default value. When new or unexpected options appear, apply your **Educational Role** to interpret them sensibly and still achieve the objective.
+
+### Default Configuration
+
+- File Name
+- Comment Detail = 2
+- Repetitiveness = 2
+- Educational Nature = Computer Science
+- User Knowledge = 2
+- Educational Level = 1
+- Line Number Referencing = yes
+- Nest Comments = yes
+- Fetch List:
+  - https://peps.python.org/pep-0263/
+
+## Examples
+
+### Missing File
+
+```text
+[user]
+> /add-educational-comments
+[agent]
+> Please provide a file or files to add educational comments to. Preferably as chat variable or attached context.
+```
+
+### Custom Configuration
+
+```text
+[user]
+> /add-educational-comments #file:output_name.py Comment Detail = 1, Repetitiveness = 1, Line Number = no
+```
+
+Interpret `Line Number = no` as `Line Number Referencing = no` and adjust behavior accordingly while maintaining all rules above.
+
+## Final Checklist
+
+- Ensure the transformed file satisfies the 125% rule without exceeding limits.
+- Keep encoding, end-of-line style, and indentation unchanged.
+- Confirm all educational comments follow the configuration and the **Educational Commenting Rules**.
+- Provide clarifying suggestions only when they aid learning.
+- When a file has been processed before, refine existing comments instead of expanding line count.

package/skills/claude/add-educational-comments/metadata.json

@@ -0,0 +1,26 @@
+{
+  "id": "add-educational-comments",
+  "name": "Add Educational Comments",
+  "type": "skill",
+  "provider": "claude",
+  "harnesses": [
+    "claude-code",
+    "cursor",
+    "copilot"
+  ],
+  "summary": "Transform code files into effective learning resources by adding contextual educational comments. Explains the 'why' behind syntax, idioms, and design choices, tailored to the learner's knowledge level and learning goals.",
+  "source_type": "original",
+  "official_docs": [
+    "https://peps.python.org/pep-0263/",
+    "https://en.wikipedia.org/wiki/Comment_(programming)"
+  ],
+  "security_notes": "Read-only skill. Only reads and annotates files with educational comments. Does not execute code, modify system state, or access sensitive data. All modifications are educational in nature and maintain original code semantics.",
+  "last_verified": "2026-05-11",
+  "path": "skills/claude/add-educational-comments/",
+  "category": "education",
+  "lifecycle": "stable",
+  "execution_tier": "local",
+  "certifications": [],
+  "author": "github: Claude",
+  "version": "1.0.0"
+}

package/skills/finops/README.md

@@ -5,26 +5,77 @@
   <span style="font-size:3.5em">💰</span>
 </p>
 
+> ⚠️ **ALPHA RELEASE** — All FinOps skills are currently at `lifecycle: experimental`. Use at your own risk in pre-production environments only. [Board readiness memo](../../docs/strategy/finops-maestro-board-memo.md) documents known limitations and 30-day diligence requirements.
+
 This folder contains cross-cloud FinOps skills curated for this marketplace.
 
 ## Local marketplace portfolio
 
-This folder contains **1** local FinOps skill:
+This folder contains **7** local FinOps skills (all alpha):
 
-- `finops-cloud-price-advisor`
+| Skill | Purpose | Lifecycle | Tools |
+|---|---|---|---|
+| `finops-maestro` | Route FinOps tasks to the narrowest specialist or parallel team (max 4) | **experimental** | Agent Skill Read Grep Glob |
+| `finops-cloud-price-advisor` | Live public pricing across AWS, Azure, OCI, Scaleway, Gandi, Alibaba, Tencent, Hetzner, Contabo, Ionos, OVHcloud | **experimental** | Read Grep Glob WebFetch |
+| `fetch-foundation-model-pricing` | Live per-token, per-image, per-GPU-hour pricing across Anthropic, OpenAI, Google, Bedrock, Azure OpenAI, OCI, and Vertex | **experimental** | Read Grep Glob WebFetch |
+| `kubernetes-allocation-report` | OpenCost-compatible namespace/pod/workload cost allocation mapped to FOCUS v1.2 columns | **experimental** | Read Grep Glob WebFetch |
+| `rightsize-recommendation` | Pod request/limit recommendations from user-supplied p50/p95/p99 metrics; Karpenter consolidation eligibility | **experimental** | Read Grep Glob |
+| `carbon-cost-pair` | Pair $ values with kgCO2e by region and service category for CSRD/SEC climate disclosure | **experimental** | Read Grep Glob WebFetch |
+| `focus-spec-normalizer` | Normalize vendor bills (AWS CUR, Azure Cost Management, GCP Billing Export, OCI) into FOCUS v1.2 columns | **experimental** | Read Grep Glob |
 
 ## Portfolio posture
 
-Cross-cloud FinOps skills for live price lookup, cost estimation, provider comparison, and budget governance.
+Cross-cloud, harness-portable FinOps skills covering AI workload economics, Kubernetes rightsizing, cross-cloud price advisory, FOCUS-spec normalization, and carbon-cost pairing.
 
 These skills are intentionally conservative:
 
-- fetch prices from public unauthenticated APIs only — no billing credentials required
+- fetch prices from public unauthenticated APIs only — no billing credentials, kubeconfig, bearer tokens, or tenant data accepted
 - always distinguish on-demand list price from effective price (reserved instances, savings plans, committed use discounts not included by default)
-- prefer live API lookups over cached or memory-based price estimates — cloud prices change frequently
-- when comparing providers, normalize compute specs (vCPU, RAM, storage type) before comparing price
-- flag GPU and accelerated compute costs explicitly — they dominate bills and are often overlooked
+- prefer live API lookups over cached or memory-based price estimates — foundation-model and cloud prices change frequently
+- when comparing providers, normalize compute specs (vCPU, RAM, GPU SKU, storage type) before comparing price
+- flag GPU and accelerated compute costs explicitly — they dominate AI workload bills
+- label every numeric output: `live-price` / `live-evidence` / `documentation-based` / `assumed` / `excluded`
+- emit FOCUS v1.2 column mappings where applicable — vendor-column adapters are explicit, not assumed
+
+### Provider coverage matrix
+
+| Category | Providers | Skill | Status |
+|---|---|---|---|
+| **Foundation models** | Anthropic, OpenAI, Google, AWS Bedrock, Azure OpenAI, OCI Generative AI, Vertex | `fetch-foundation-model-pricing` | experimental |
+| **Cloud compute (on-demand)** | AWS, Azure, OCI | `finops-cloud-price-advisor` | experimental |
+| **Cloud compute (regional)** | Scaleway (EU), Gandi (EU), Alibaba Cloud (CN/APAC), Tencent Cloud (CN/APAC), Hetzner (EU), Contabo (EU), Ionos (EU), OVHcloud (EU) | `finops-cloud-price-advisor` | experimental |
+| **Kubernetes cost** | EKS, AKS, GKE, OKE (vendor-agnostic allocation) | `kubernetes-allocation-report` + `rightsize-recommendation` | experimental |
+| **Bill normalization** | AWS CUR, Azure Cost Management, GCP Billing Export, OCI Cost Analysis | `focus-spec-normalizer` | experimental |
+| **Carbon tracking** | AWS, Azure, GCP, OCI | `carbon-cost-pair` | experimental |
+
+## 🧭 Routing taxonomy
+
+See [agents/finops/README.md](../agents/README.md) for the complete 120+ keyword taxonomy used by `finops-maestro` to classify and dispatch tasks to the right specialist skill or agent.
+
+## ⚠️ Known limitations and disclaimers
+
+**Alpha status**: These skills support pre-production research and estimation use cases. Production deployment requires:
+1. Signed design-partner SOW with cost verification clause
+2. AT-C 215 AUP report from Big 4 accounting firm documenting hard savings
+3. SOC 2 Type II observation (≥150 days) on infrastructure
+4. FOCUS v1.2 column-mapping audit by compliance reviewer
+
+**Data freshness**: Cloud and foundation-model prices are live-fetched on every invocation. Pricing APIs are public and unauthenticated; no caching across sessions. If a pricing API is unavailable, the skill returns a documented-based fallback with a timestamp.
+
+**Scope limitations**:
+- Reserved instances, savings plans, committed use discounts require separate calculation (not included in base list-price estimates)
+- Volume discounts (multi-year, enterprise agreements) not modeled
+- Spot/preemptible pricing not included (separate query required)
+- Custom pricing (e.g., negotiated cloud contracts) not discoverable
+
+**Accuracy**: Cost estimates from these skills are **indicative only**. Use them for:
+- Budget planning (±20% accuracy acceptable)
+- Comparative analysis (which cloud is cheaper?)
+- Anomaly detection (which workload got expensive?)
 
-Providers covered: 🟧 AWS Price List API · 🟦 Azure Retail Prices API · 🟥 OCI public pricing API
+Do not use for:
+- Chargeback / cost allocation without human review
+- SLA-level cost forecasting
+- Contractual billing disputes
 
-Run `npm run validate` after changing cataloged FinOps skills.
+**See also**: [Board readiness memo Section 8](../../docs/strategy/finops-maestro-board-memo.md#8-risk-catalog) enumerates all 21 operational risks with contractual mitigations.

package/skills/finops/carbon-cost-pair/README.md

@@ -0,0 +1,25 @@
+# Carbon Cost Pair
+
+A FinOps skill that pairs cloud spend values with kgCO2e carbon estimates by region and service category, with mandatory confidence labels and source citations for CSRD and SEC climate disclosure.
+
+## Purpose
+
+For every cloud spend line item, produce a paired kgCO2e estimate using the best available carbon factor for the cloud region and service category. Confidence is labeled as `vendor-published`, `third-party`, or `estimated`, and every output includes a source URL and data period acknowledgment.
+
+## Allowed tools
+
+`Read` `Grep` `Glob` `WebFetch`
+
+## Usage
+
+**Single line item:** Provide cloud provider, region, service category, and dollar value (e.g., "Pair $1,200 of AWS us-east-1 compute spend with a carbon estimate"). The skill fetches the latest available carbon factor, applies it, and returns a labeled kgCO2e output with FOCUS tag mapping.
+
+**Multi-line comparison:** Provide multiple regions or providers (e.g., "Compare carbon intensity for the same $10,000 compute spend across AWS us-east-1, Azure eastus, and GCP us-central1"). The skill returns one estimate block per line item plus a summary comparison table.
+
+## Trust posture
+
+Read-only. No cloud credentials, billing account IDs, or tenant data accepted. Carbon factors are fetched from public provider sustainability pages or third-party sources. Provider data typically lags 60-90 days; the data period is stated in every output.
+
+Defaults to Scope 2 electricity-only, market-based factors. Location-based and Scope 1+2 available on request.
+
+See [SKILL.md](SKILL.md) for the full operating rules, confidence label decision tree, regulatory context, and output shape.

package/skills/finops/carbon-cost-pair/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: carbon-cost-pair
+description: Pair every cloud spend value with a kgCO2e estimate by region and service category for CSRD and SEC climate disclosure. Input is region, service category, and dollar value; output is paired kgCO2e with confidence label (vendor-published, third-party, or estimated) and source citation. Defaults to electricity-only Scope 2 market-based factors.
+allowed-tools: Read Grep Glob WebFetch
+metadata:
+  author: "github: Raishin"
+  version: "0.1.1"
+  updated: "2026-05-13"
+  category: finops
+  lifecycle: experimental
+---
+
+# Carbon Cost Pair
+
+## Purpose
+
+For every cloud spend line item, produce a paired kgCO2e estimate suitable for CSRD and SEC climate disclosure. The skill pairs a dollar value (or resource quantity) with the best available carbon emissions factor for the given cloud region and service category, and returns the estimate with a mandatory confidence label and source citation.
+
+No cloud credentials accepted. Carbon factors are fetched from provider sustainability pages or third-party sources.
+
+## When to use
+
+Use this skill when:
+
+- The user needs to pair a cloud spend or usage figure with a carbon estimate for sustainability reporting (CSRD Article 29a, SEC climate rule, GHG Protocol Scope 2)
+- The user wants to compare the carbon intensity of the same workload across cloud regions or providers
+- The user wants to understand the confidence level of a carbon estimate before including it in a regulatory disclosure
+
+## Operating rules
+
+- **Default to electricity-only Scope 2, market-based.** Unless the caller specifies otherwise, compute Scope 2 emissions using market-based electricity factors (renewable energy certificate or PPA-adjusted). Location-based factors are available on request.
+- **Fetch live data first.** Use WebFetch to retrieve the latest carbon factor data from the provider's sustainability API or dashboard before falling back to documentation-based estimates.
+- **Confidence labels mandatory.** Every kgCO2e output must carry exactly one label:
+  - `vendor-published` — factor sourced from the provider's own sustainability API, dashboard, or data export within this session (include source URL and ISO 8601 timestamp)
+  - `third-party` — factor sourced from Electricity Maps, Cloud Carbon Footprint project, or equivalent third-party source (include source URL and timestamp)
+  - `estimated` — factor derived from regional grid average or published industry emission factors where no provider or third-party data is available (state the factor, source, and assumptions)
+- **No credentials accepted.** No cloud credentials, billing account IDs, tenant data, or sustainability API tokens are accepted or required.
+- **Acknowledge data lag.** Provider carbon data typically lags 60-90 days or more. State the data period whenever citing vendor-published factors.
+- **FOCUS column mapping.** There are no native FOCUS v1.2 carbon columns. Represent carbon estimates as FOCUS tags: `Tags/kgco2e`, `Tags/carbon_confidence`, `Tags/carbon_source`.
+- **Load references only when needed.**
+
+## Input
+
+| Field | Required | Description |
+|---|---|---|
+| Cloud provider | Yes | AWS, Azure, Google Cloud, OCI, or multi-cloud |
+| Region | Yes | Provider region name (e.g., `us-east-1`, `eastus`, `us-central1`, `ap-sydney-1`) |
+| Service category | Yes | Compute, Storage, Networking, AI and Machine Learning, Databases, or Other |
+| Dollar value ($) | Yes | The spend amount to pair with a carbon estimate |
+| Resource quantity | Optional | If available, the underlying resource quantity (e.g., vCPU-hours, GiB-hours, GB transferred) for a more precise estimate |
+| Scope preference | Optional | Default: Scope 2 market-based. Options: `scope2-market`, `scope2-location`, `scope1+2` |
+
+## Output shape
+
+Return, per line item:
+
+```
+Region:           <provider region>
+Service category: <category>
+Dollar value:     $<amount>
+kgCO2e estimate:  <value> kgCO2e  [<confidence label>]
+Scope:            Scope 2 (market-based)  |  Scope 2 (location-based)
+Data period:      <e.g., Q3 2025 or "Current as of 2026-05-13">
+Source:           <URL>  (fetched: <ISO 8601 timestamp>  |  documentation date: <date>)
+Methodology note: <one sentence describing the emission factor used>
+
+FOCUS tags:
+  Tags/kgco2e:           <value>
+  Tags/carbon_confidence: <vendor-published | third-party | estimated>
+  Tags/carbon_source:     <URL>
+```
+
+If multiple regions or service categories are provided, return one block per line item followed by a summary table.
+
+## Confidence label decision tree
+
+1. Does the cloud provider publish a region-level carbon factor or API for this region and service?
+   - Yes, and it was fetched this session → `vendor-published`
+   - Yes, but the fetch failed or data is not current → proceed to step 2
+2. Is Electricity Maps data available for the grid region, or is Cloud Carbon Footprint data available for this provider/region?
+   - Yes → `third-party`
+3. Fall back to IEA regional grid average emission factor or the provider's country-level average.
+   - → `estimated`; state the factor used (e.g., `0.386 kgCO2e/kWh — IEA 2023 US average`)
+
+## Regulatory context
+
+- **CSRD (Corporate Sustainability Reporting Directive)**: requires disclosure of Scope 1, 2, and 3 emissions under ESRS E1. Cloud compute is typically Scope 2 (purchased electricity) and may contribute to Scope 3 Category 1 (purchased goods/services) for customers.
+- **SEC Climate Rule**: requires material climate-related disclosures including Scope 1 and 2 emissions for large accelerated filers.
+- **GHG Protocol**: defines market-based and location-based approaches for Scope 2. Both may be required; market-based is the default here.
+
+## References
+
+Load these only when needed:
+
+- [Carbon data sources](references/sources.md) — provider sustainability API URLs, third-party data sources, and fallback options.
+- [Methodology](references/methodology.md) — market-based vs location-based Scope 2, data lag, and uncertainty labeling.

package/skills/finops/carbon-cost-pair/metadata.json

@@ -0,0 +1,27 @@
+{
+  "id": "carbon-cost-pair",
+  "name": "Carbon Cost Pair",
+  "type": "skill",
+  "provider": "multi-cloud",
+  "harnesses": [
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "kiro",
+    "other"
+  ],
+  "summary": "Pair cloud spend values with kgCO2e estimates by region and service category for CSRD and SEC climate disclosure. Outputs confidence-labeled carbon estimates (vendor-published, third-party, or estimated) with source citations. Defaults to Scope 2 market-based electricity factors.",
+  "source_type": "original",
+  "official_docs": [
+    "https://aws.amazon.com/aws-cost-management/aws-customer-carbon-footprint-tool/",
+    "https://learn.microsoft.com/en-us/industry/sustainability/",
+    "https://cloud.google.com/carbon-footprint/docs"
+  ],
+  "security_notes": "No cloud credentials, billing account IDs, sustainability API tokens, or tenant-specific data are accepted or required. All carbon factors are fetched from public provider sustainability pages or third-party data sources. No write operations to any system are performed.",
+  "last_verified": "2026-05-13",
+  "path": "skills/finops/carbon-cost-pair",
+  "author": "github: Raishin",
+  "version": "0.1.1",
+  "lifecycle": "experimental"
+}