fix: make skill publish idempotent by name/version

Signed-off-by: Michael Kantor <6068672+kantorcodes@users.noreply.github.com>

Author: kantorcodes

README.md

@@ -10,9 +10,13 @@ Canonical docs and API surfaces:
 - Registry landing page: https://hol.org/registry
 - Skill index: https://hol.org/registry/skills
 - Skill manifest schema: https://raw.githubusercontent.com/hashgraph-online/skill-publish/main/schemas/skill.schema.json
-- API docs: https://hol.org/registry/docs
+- Product docs: https://hol.org/docs/registry-broker/
+- Interactive API docs: https://hol.org/registry/docs
 - OpenAPI schema: https://hol.org/registry/api/v1/openapi.json
+- Live stats endpoint: https://hol.org/registry/api/v1/dashboard/stats
 - APIs.json metadata: https://hol.org/registry/apis.json
+- Repository APIs.json: https://raw.githubusercontent.com/hashgraph-online/skill-publish/main/apis.json
+- Repository LLM index: https://raw.githubusercontent.com/hashgraph-online/skill-publish/main/llms.txt
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18748325.svg?style=for-the-badge)](https://doi.org/10.5281/zenodo.18748325)
 [![HOL Registry](https://img.shields.io/badge/HOL-Registry-5599FE?style=for-the-badge)](https://hol.org/registry)
@@ -54,6 +58,8 @@ jobs:
 
 - Zenodo metadata: [`.zenodo.json`](./.zenodo.json)
 - Citation metadata: [`CITATION.cff`](./CITATION.cff)
+- Schema validation workflow: [`.github/workflows/schema-validate.yml`](./.github/workflows/schema-validate.yml)
+- Release workflow: [`.github/workflows/release.yml`](./.github/workflows/release.yml)
 
 ## Required secret
 
@@ -88,11 +94,12 @@ jobs:
 The action:
 
 1. Validates package files and `/skills/config` constraints.
-2. Calls `POST /skills/quote`.
-3. Calls `POST /skills/publish`.
-4. Polls `GET /skills/jobs/{jobId}` until completion.
-5. Stamps `repo` and `commit` metadata in `skill.json` payload by default.
-6. Appends publish result details to release notes (release events) or merged PR comments (push to `main`) when annotation is enabled.
+2. Checks whether the exact `name@version` already exists and skips publish when it does.
+3. Calls `POST /skills/quote` when publish is needed.
+4. Calls `POST /skills/publish`.
+5. Polls `GET /skills/jobs/{jobId}` until completion.
+6. Stamps `repo` and `commit` metadata in `skill.json` payload by default.
+7. Appends publish result details to release notes (release events) or merged PR comments (push to `main`) when annotation is enabled.
 
 ## Cite this repository
 

entrypoint.mjs

@@ -176,6 +176,33 @@ const requestJson = async (params) => {
   return response.json();
 };
 
+const findExistingSkillVersion = async (params) => {
+  const { apiBaseUrl, apiKey, name, version } = params;
+  const response = await requestJson({
+    method: 'GET',
+    url: buildApiUrl(apiBaseUrl, '/skills/list', {
+      name,
+      version,
+      limit: 20,
+    }),
+    apiKey,
+  });
+
+  const items = Array.isArray(response?.items) ? response.items : [];
+  for (const item of items) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      continue;
+    }
+    const itemName = typeof item.name === 'string' ? item.name.trim() : '';
+    const itemVersion = typeof item.version === 'string' ? item.version.trim() : '';
+    if (itemName === name && itemVersion === version) {
+      return item;
+    }
+  }
+
+  return null;
+};
+
 const parseEventPayload = async () => {
   const eventPath = getEnv('GITHUB_EVENT_PATH');
   if (!eventPath) {
@@ -237,15 +264,19 @@ const buildPublishMarkdown = (result) => {
   const lines = [];
   lines.push('### HCS-26 skill publish result');
   lines.push('');
+  lines.push(`- Status: \`${result.published === false ? 'skipped' : 'published'}\``);
   lines.push(`- Name: \`${result.skillName}\``);
   lines.push(`- Version: \`${result.skillVersion}\``);
-  lines.push(`- Quote ID: \`${result.quoteId}\``);
-  lines.push(`- Job ID: \`${result.jobId}\``);
+  lines.push(`- Quote ID: \`${result.quoteId || 'n/a'}\``);
+  lines.push(`- Job ID: \`${result.jobId || 'n/a'}\``);
   lines.push(`- Directory Topic: \`${result.directoryTopicId ?? 'n/a'}\``);
   lines.push(`- Package Topic: \`${result.packageTopicId ?? 'n/a'}\``);
   lines.push(`- skill.json HRL: \`${result.skillJsonHrl ?? 'n/a'}\``);
-  lines.push(`- Credits: \`${result.credits}\``);
-  lines.push(`- Estimated Cost: \`${result.estimatedCostHbar} HBAR\``);
+  lines.push(`- Credits: \`${result.credits ?? 0}\``);
+  lines.push(`- Estimated Cost: \`${result.estimatedCostHbar ?? '0'} HBAR\``);
+  if (result.published === false && result.skippedReason) {
+    lines.push(`- Skip reason: \`${result.skippedReason}\``);
+  }
   lines.push('');
   lines.push(`- Repo: \`${result.repoUrl ?? 'n/a'}\``);
   lines.push(`- Commit: \`${result.commitSha ?? 'n/a'}\``);
@@ -417,6 +448,62 @@ const run = async () => {
     throw new ActionError('skill.json must include description.');
   }
 
+  const existingVersion = await findExistingSkillVersion({
+    apiBaseUrl,
+    apiKey,
+    name: skillName,
+    version: skillVersion,
+  });
+
+  if (existingVersion) {
+    const result = {
+      skillName,
+      skillVersion,
+      quoteId: '',
+      jobId: '',
+      directoryTopicId:
+        typeof existingVersion.directoryTopicId === 'string'
+          ? existingVersion.directoryTopicId
+          : null,
+      packageTopicId:
+        typeof existingVersion.packageTopicId === 'string'
+          ? existingVersion.packageTopicId
+          : typeof existingVersion.versionRegistryTopicId === 'string'
+            ? existingVersion.versionRegistryTopicId
+            : null,
+      skillJsonHrl:
+        typeof existingVersion.skillJsonHrl === 'string'
+          ? existingVersion.skillJsonHrl
+          : typeof existingVersion.manifestHrl === 'string'
+            ? existingVersion.manifestHrl
+            : null,
+      credits: 0,
+      estimatedCostHbar: '0',
+      repoUrl: repoUrl || null,
+      commitSha: commitSha || null,
+      published: false,
+      skippedReason: 'version-exists',
+    };
+
+    stdout(`Skill version ${skillName}@${skillVersion} already exists. Skipping publish.`);
+
+    const markdown = buildPublishMarkdown(result);
+    await appendStepSummary(markdown);
+
+    await setActionOutput('skill-name', result.skillName);
+    await setActionOutput('skill-version', result.skillVersion);
+    await setActionOutput('quote-id', '');
+    await setActionOutput('job-id', '');
+    await setActionOutput('directory-topic-id', result.directoryTopicId ?? '');
+    await setActionOutput('package-topic-id', result.packageTopicId ?? '');
+    await setActionOutput('skill-json-hrl', result.skillJsonHrl ?? '');
+    await setActionOutput('annotation-target', 'none');
+    await setActionOutput('result-json', JSON.stringify(result, null, 2));
+
+    stdout(markdown);
+    return;
+  }
+
   const config = await requestJson({
     method: 'GET',
     url: buildApiUrl(apiBaseUrl, '/skills/config'),