{ "schemaVersion": "1.0", "item": { "slug": "skill-provenance", "name": "Skill Provenance", "source": "tencent", "type": "skill", "category": "AI 智能", "sourceUrl": "https://clawhub.ai/snapsynapse/skill-provenance", "canonicalUrl": "https://clawhub.ai/snapsynapse/skill-provenance", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/skill-provenance", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=skill-provenance", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "evals-distribution.json", "evals.json", "README.md", "MANIFEST.yaml", "SKILL.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/skill-provenance" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/skill-provenance", "agentPageUrl": "https://openagent3.xyz/skills/skill-provenance/agent", "manifestUrl": "https://openagent3.xyz/skills/skill-provenance/agent.json", "briefUrl": "https://openagent3.xyz/skills/skill-provenance/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "The Problem This Solves", "body": "Skill projects move between sessions, surfaces (Chat, IDE, CLI, Cowork),\nplatforms (Claude, Gemini CLI, Codex, Copilot), and local storage\n(Obsidian, working directories, git repos). Version identity gets lost\nwhen it lives only in filenames. A file renamed from SKILL_v4.md to\nSKILL_v5.md with no internal record of what changed creates ambiguity.\n\nThis skill establishes three conventions that prevent that:\n\nVersion identity lives inside files when their format allows it, and\nalways in the manifest.\nA recent changelog travels with the skill bundle, while longer history\ncan live in the source repo.\nA manifest lists all files in the bundle so any session can verify completeness." }, { "title": "What Gets Versioned", "body": "A skill bundle is a SKILL.md plus all associated files. Typical contents:\n\nSKILL.md (the skill definition)\nevals.json (evaluation suite)\nGeneration scripts (e.g., generate.js, generate.py)\nOutput artifacts (.docx, .pdf) produced by evals or real use\nHandoff notes\nSource material provided by the user (tracked but not versioned)\n\nThe skill itself (SKILL.md) and evals are the primary versioned artifacts.\nScripts and outputs are tracked by the manifest but version with the bundle\nrather than independently. Handoff notes are optional convenience artifacts." }, { "title": "Internal Version Header", "body": "Files that can safely carry YAML frontmatter begin with a YAML frontmatter\nblock (or extend an existing one) containing these fields:\n\n---\nskill_bundle: my-skill # bundle name, stable across versions\nfile_role: skill # skill | evals | script | output | handoff\nversion: 5 # integer, monotonically increasing\nversion_date: 2026-02-10 # date of this version\nprevious_version: 4 # null for v1\nchange_summary: >\n Rewrote Phase 5 layout rules. Removed per-section page breaks.\n Added content flow check. Added validation checklist as standalone final page.\n---" }, { "title": "Rules", "body": "version is an integer for per-file tracking. It counts revisions to\nthat specific file within the bundle. The bundle-level version\n(bundle_version in MANIFEST.yaml) uses semver.\n\nchange_summary is required for every version after v1. One to three\nsentences. It must describe what changed, not just that something changed.\n\nprevious_version creates a chain. Any session can trace the lineage.\n\nfile_role values:\n\nskill — the SKILL.md itself\nevals — the evals.json file\nscript — generation scripts, utility scripts\noutput — rendered artifacts (.docx, .pdf)\nhandoff — session handoff notes\nsource — user-provided source material (tracked, not versioned)\nreference — documentation in references/ loaded on demand\nasset — templates, images, fonts in assets/ used in output\nagents — platform UI metadata (e.g., Codex's agents/openai.yaml)\n\nFor files that cannot safely carry YAML frontmatter (binary files and\nstrict-format files such as .json or executable .sh), the manifest\ntracks their version and its version field is authoritative.\n\nSKILL.md frontmatter constraint: The Agent Skills open standard\n(agentskills.io) requires name and description. Different platforms\nenforce different rules about additional fields:\n\nPlatformAllowed SKILL.md frontmatteragentskills.io specname, description, license, metadata, compatibility, allowed-toolsClaude Chat / Settings UISame as spec. Claude's settings importer rejects unrecognized fields.Claude CodeSpec fields plus extensions: disable-model-invocation, user-invocable, context, agent, model, hooks, argument-hint. These are Claude Code features, not part of the base spec.Claude APISkills uploaded via /v1/skills. Validates name and description. Supports metadata.Gemini CLI (Google)name and description only. Extra fields not officially supported.Codex (OpenAI)name and description only. Extra fields rejected.GitHub Copilot / VS CodeFollows agentskills.io spec.Cursor, Roo Code, Junie, othersFollows agentskills.io spec. See agentskills.io for the full adopter list (30+).\n\nFor maximum portability, keep SKILL.md frontmatter to name and\ndescription only. If the canonical bundle needs attribution or visible\nSKILL.md metadata, use the spec's metadata field there and generate a\nderived minimal copy for strict platforms:\n\n---\nname: my-skill\ndescription: What the skill does.\nmetadata:\n skill_bundle: my-skill\n file_role: skill\n version: 3\n version_date: 2026-02-10\n previous_version: 2\n change_summary: >\n Added Phase 6 validation step.\n---\n\nIf targeting Codex or other strict platforms directly, omit metadata\nfrom SKILL.md entirely. The manifest tracks SKILL.md's version either\nway, so no version information is lost.\n\nNote on spec support: The agentskills.io spec formally supports\nmetadata as an arbitrary key-value map, with version shown as an\nexample use. This means the metadata.version approach is now\nspec-blessed, not a Claude-only extension. However, the spec's version\nis a static label — it does not address staleness tracking, changelogs,\nor bundle integrity. Prefer manifest-based tracking as the default and\nuse metadata only when you need version info visible in the file\nitself." }, { "title": "Manifest", "body": "The manifest is a YAML file named MANIFEST.yaml at the root of the skill\nbundle directory — the same level as SKILL.md. When the bundle is\npackaged as a .skill ZIP, the manifest lives inside the ZIP. It is the\nsingle source of truth for what the bundle contains.\n\nbundle: my-skill\nbundle_version: 5.1.0\nbundle_date: 2026-02-10\ndescription: >\n Skill for generating professional documents from source material\n and user briefs. Handles research, structuring, and formatting.\n\ncompatibility:\n designed_for:\n surfaces:\n - chat\n - cli\n - ide\n capabilities:\n - minimal SKILL.md frontmatter\n - local filesystem access\n - optional git workflow\n tested_on:\n - platform: Anthropic Claude\n model: Claude Opus 4.6\n surface: Chat\n status: pass\n date: 2026-02-10\n - platform: Anthropic Claude\n model: Claude Sonnet 4.5\n surface: Chat\n status: partial\n date: 2026-02-09\n notes: Misses staleness detection on complex bundles\n spec_version: agentskills.io/1.0\n frontmatter_mode: minimal\n # minimal = name + description only (Codex, Gemini CLI, max portability)\n # metadata = includes metadata block (any platform supporting the spec's metadata field)\n\ndependencies: []\n # List skill names this bundle depends on. Omit or leave empty if none.\n\ndeployments:\n api:\n version: 1759178010641129\n workspace: docs-prod\n claude:\n scope: user\n perplexity:\n package_format: zip\n\nfiles:\n - path: SKILL.md\n role: skill\n version: 5\n hash: sha256:abc123...\n note: Canonical skill definition\n\n - path: evals.json\n role: evals\n version: 3\n hash: sha256:def456...\n note: 7 evals including real-content synthesis\n\n - path: scripts/generate.js\n role: script\n version: 4\n hash: sha256:ghi789...\n note: Generation script for eval 3\n\n - path: outputs/eval3-output.pdf\n role: output\n version: 4\n hash: sha256:jkl012...\n note: Rendered eval 3 output, 10 pages, validated\n\n - path: sources/article-1.md\n role: source\n version: null\n hash: sha256:pqr678...\n note: Source article 1 (published)" }, { "title": "Rules", "body": "bundle_version uses semver (MAJOR.MINOR.PATCH). Bump MAJOR for\nbreaking changes to the skill's model or interface, MINOR for new\nfeatures or capabilities, PATCH for fixes and documentation updates.\nPer-file version fields remain integers — they are revision counters,\nnot release identifiers.\n\nhash is sha256 of the file contents. This is how a new session verifies\nthat the file it received matches what the manifest claims. Compute on save,\nverify on load.\n\ndeployments is optional. Use it to record deployed or installed copies\nof the same bundle when you want traceability across surfaces. Keep\nbundle_version as the author-side semver source of truth. Platform-native\nversions (for example API timestamps) stay in deployments, not in\nbundle_version.\n\nversion: null for source files. They are tracked for completeness but\nnot versioned by this system.\n\nPaths are relative to the bundle root. No absolute paths.\n\nMANIFEST.yaml is not listed in files. Self-hashing is recursive. Treat\nthe manifest as the bundle's control file and verify it via git, transport\nchecksums, or the surrounding package when needed." }, { "title": "The .skill Package Format", "body": "Claude's settings UI exports and imports skills as .skill files. These\nare standard ZIP archives containing a directory named after the skill.\nThe versioning artifacts (MANIFEST.yaml, CHANGELOG.md, README.md)\nlive inside this directory at the same level as SKILL.md:\n\nskill-name.skill (ZIP)\n└── skill-name/\n ├── SKILL.md\n ├── MANIFEST.yaml\n ├── CHANGELOG.md\n ├── README.md\n ├── assets/\n └── references/\n\nClaude's settings importer only looks for SKILL.md and the directory\nstructure it expects (references, assets). It ignores files it doesn't\nrecognize. This means the versioning artifacts travel safely inside the\n.skill ZIP without affecting import/export behavior.\n\nWhen bootstrapping or updating a bundle, always include the versioning\nartifacts in the .skill ZIP so they survive round-trips through\nClaude's settings UI.\n\nSome uploaders only accept .zip or .md. In those cases, rename the\narchive from .skill to .zip without changing its contents.\n\nThe spec recommends keeping SKILL.md under 500 lines and moving detailed\nreference material to separate files. Provenance artifacts fit naturally\ninto that model: MANIFEST.yaml and CHANGELOG.md are load-on-demand\nresources, not always-loaded instructions.\n\nClaude Code provides a ${CLAUDE_SKILL_DIR} variable for bundle-relative\npaths. Other platforms may not. Direct relative paths like\n./validate.sh work when the working directory is the bundle root.\n\nThe .skill ZIP only carries the skill definition and its references.\nBundles can still track evals, scripts, rendered outputs, and handoff\nnotes outside the archive. The manifest remains the complete inventory,\nnot just the package inventory." }, { "title": "Changelog", "body": "The changelog is a file named CHANGELOG.md at the root of the skill\nbundle directory, alongside SKILL.md and MANIFEST.yaml. In the\nbundle, it carries recent history with newest entries at the top. If the\ncanonical source lives in git, older entries can be archived in a\nrepo-level changelog outside the bundle.\n\n# Changelog\n\n## 5.1.0 — 2026-02-10\n- SKILL.md: Rewrote Phase 5 layout rules. Removed per-section page breaks.\n Added content flow check and a standalone validation checklist.\n- evals.json: Not yet updated (stale, needs alignment).\n\n## 5.0.0 — 2026-02-09\n- SKILL.md: Reworked body flow rules and added an optional appendix.\n- evals.json: Eval 3 expectations updated for content flow." }, { "title": "Rules", "body": "Each entry names every file that changed and what changed in it.\n\nFiles that are stale get called out. If SKILL.md changes but evals.json\nwas not updated to match, the changelog says so. This prevents the silent\ndrift that caused the v4/v5 confusion.\n\nEntries are human-written prose, not auto-generated diffs. The point is\nto communicate intent, not enumerate line changes. Git diffs are available\nwhen the bundle is in git.\n\nBundle changelogs can be trimmed. Keeping the last 5-15 entries in\nthe bundle is reasonable if the source repository maintains a full\nappend-only changelog elsewhere." }, { "title": "Opening a session", "body": "When a skill bundle is loaded into a new session:\n\nRead MANIFEST.yaml first.\nVerify all listed files are present. Report any missing files.\nFor files with hashes, verify hashes match. Flag mismatches. In\nlocal environments, users can run validate.sh before uploading\nfor reliable hash verification without LLM computation.\nRead CHANGELOG.md to understand recent changes.\nCheck for staleness: if any file's version is lower than the bundle\nversion, or if deployments clearly show a deployed copy behind the\nlocal bundle, flag it and ask the user whether it needs updating.\nIf MANIFEST.yaml is missing, treat the bundle as unversioned. Offer\nto create one by inventorying the files and asking the user for version\ncontext." }, { "title": "Saving / closing a session", "body": "When work is complete and files are being delivered:\n\nUpdate internal version headers for changed files that use them.\n\n\nUpdate MANIFEST.yaml with new versions and hashes for every changed\nversioned file, including manifest-only files. If the user deployed or\nreinstalled the skill this session, update any relevant deployments\nmetadata too.\n\n\nAdd a new top entry to CHANGELOG.md.\n\n\nIf any versioned file was changed but another dependent file was not\nupdated (e.g., SKILL.md changed but evals.json was not updated), note\nthe staleness explicitly in the changelog entry.\n\n\nDeliver the full bundle to the user, or at minimum the changed files\nplus the updated MANIFEST.yaml and CHANGELOG.md.\n\n\nIf the user indicates the bundle is destined for a git repo, provide\na ready-to-use commit message derived from the changelog entry. Format:\nskill-name MAJOR.MINOR.PATCH: one-line summary\n\n- file1.md: what changed\n- file2.json: what changed\n- Stale: file3.js (not updated this session)\n\nReturn the message inline by default. Only write a transient\ngit_commit.txt file if the user explicitly asks for a file or if the\nenvironment makes file output materially more convenient." }, { "title": "Handoff between sessions", "body": "A handoff note is a snapshot of project state for the next session. It\nshould include:\n\nCurrent bundle version\nWhat was accomplished this session\nWhat is stale and needs attention\nWhat the next session should do first\nAny decisions made that are not yet reflected in the files\nPer-file change summaries: for each file modified this session, a\nbrief description of what changed (section added, field removed,\nlogic rewritten, etc.). This is more granular than the changelog\nentry and helps the next session verify the work without re-reading\nevery file.\n\nCreate a handoff note only when crossing a non-persistent boundary or when\nthe user explicitly asks for one. In filesystem-native environments with a\ncurrent manifest, changelog, and git history, it is usually unnecessary.\nWhen created, it replaces the previous handoff note; previous handoffs live\nin changelog history." }, { "title": "Conflict resolution", "body": "When a session finds version conflicts (e.g., a file claims v5 but the\nmanifest says v4, or two files claim different bundle versions):\n\nPresent the conflict to the user with the specific discrepancy.\nShow what each version claims via its change_summary.\nDefault recommendation: trust the most recent version_date.\nAlways ask the user for explicit confirmation before proceeding.\n\nNever silently resolve a version conflict. The whole point of this system\nis to make conflicts visible." }, { "title": "Cross-Surface and Cross-Platform Considerations", "body": "Treat one skill as moving through three states:\n\nCanonical source bundle: The working copy in git or local storage.\nKeep MANIFEST.yaml and the active CHANGELOG.md here. This is the\nauthor-side source of truth. If you maintain a full archive in git,\nkeep it at repo root or another repo-level path outside the bundle.\nStrict-platform install copy: A derived copy for Codex, Gemini CLI,\nPerplexity, or other loaders that only accept name and description.\nStrip the metadata block from SKILL.md, set frontmatter_mode: minimal, recompute hashes in that copy, and leave the canonical bundle\nunchanged unless you intentionally promote the derived copy.\nRegistry or settings package: A consumer package such as a .skill\nZIP or ClawHub upload. It may omit development-only files, but its\nMANIFEST.yaml must describe exactly what the package contains. Update\ndeployments only after a real publish, reinstall, or redeploy.\n\nSurface notes:\n\nClaude Chat: Stateless upload/download boundary. Verify on open and\nconsider a handoff note.\nClaude Cowork / Claude Code / Claude Agent SDK: Persistent\nfilesystem. The manifest and changelog live with the bundle.\nClaude API: Deployment versions live in deployments, not in\nbundle_version.\nOther agentskills clients: Unknown files are ignored safely.\n.agents/skills/ can act as a neutral install path.\n\nGeneral principle: the manifest and changelog stay authoritative, and\ntransformed install or publish copies are derived artifacts, not silent\nedits to the canonical bundle." }, { "title": "Trust and Audit", "body": "Use the manifest, changelog, hashes, and optional deployment metadata to\nverify what belongs in the bundle, whether files still match their\nrecorded state, what changed, and which installed or deployed copies may\nnow be stale. If a bundle comes from an untrusted source, verify it first." }, { "title": "File Naming", "body": "Versioned files use stable names without version numbers:\n\nSKILL.md (not SKILL_v5.md)\nevals.json (not evals_v3.json)\ngenerate.js (not generate-v4.js)\n\nThe version lives inside the file (via the header) and in the manifest,\nnot in the filename. Version-numbered filenames are how we got into\ntrouble in the first place.\n\nException: if a user's local storage requires version-in-filename for\ntheir workflow, the manifest is the tiebreaker for which version is\ncanonical. Internal version identity must still match." }, { "title": "Bootstrap", "body": "To version an existing unversioned skill bundle:\n\nInventory all files present — read the directory structure or uploaded\nfile list. Do not ask the user to list files; determine this yourself.\nAsk the user what version number to assign. If there's a handoff note\nor other context, propose a number based on the history.\nAdd internal version headers to files that can safely carry them and\nrecord manifest-only versions for strict-format files.\nGenerate MANIFEST.yaml with hashes.\nCreate CHANGELOG.md with a single entry summarizing known history.\nDeliver the versioned bundle.\n\nThis is a one-time operation per skill bundle." }, { "title": "Origin", "body": "Developed by Snap Synapse. Canonical source:\nhttps://github.com/snapsynapse/skill-provenance" } ], "body": "Skill Provenance\nThe Problem This Solves\n\nSkill projects move between sessions, surfaces (Chat, IDE, CLI, Cowork), platforms (Claude, Gemini CLI, Codex, Copilot), and local storage (Obsidian, working directories, git repos). Version identity gets lost when it lives only in filenames. A file renamed from SKILL_v4.md to SKILL_v5.md with no internal record of what changed creates ambiguity.\n\nThis skill establishes three conventions that prevent that:\n\nVersion identity lives inside files when their format allows it, and always in the manifest.\nA recent changelog travels with the skill bundle, while longer history can live in the source repo.\nA manifest lists all files in the bundle so any session can verify completeness.\nWhat Gets Versioned\n\nA skill bundle is a SKILL.md plus all associated files. Typical contents:\n\nSKILL.md (the skill definition)\nevals.json (evaluation suite)\nGeneration scripts (e.g., generate.js, generate.py)\nOutput artifacts (.docx, .pdf) produced by evals or real use\nHandoff notes\nSource material provided by the user (tracked but not versioned)\n\nThe skill itself (SKILL.md) and evals are the primary versioned artifacts. Scripts and outputs are tracked by the manifest but version with the bundle rather than independently. Handoff notes are optional convenience artifacts.\n\nInternal Version Header\n\nFiles that can safely carry YAML frontmatter begin with a YAML frontmatter block (or extend an existing one) containing these fields:\n\n---\nskill_bundle: my-skill # bundle name, stable across versions\nfile_role: skill # skill | evals | script | output | handoff\nversion: 5 # integer, monotonically increasing\nversion_date: 2026-02-10 # date of this version\nprevious_version: 4 # null for v1\nchange_summary: >\n Rewrote Phase 5 layout rules. Removed per-section page breaks.\n Added content flow check. Added validation checklist as standalone final page.\n---\n\nRules\n\nversion is an integer for per-file tracking. It counts revisions to that specific file within the bundle. The bundle-level version (bundle_version in MANIFEST.yaml) uses semver.\n\nchange_summary is required for every version after v1. One to three sentences. It must describe what changed, not just that something changed.\n\nprevious_version creates a chain. Any session can trace the lineage.\n\nfile_role values:\n\nskill — the SKILL.md itself\nevals — the evals.json file\nscript — generation scripts, utility scripts\noutput — rendered artifacts (.docx, .pdf)\nhandoff — session handoff notes\nsource — user-provided source material (tracked, not versioned)\nreference — documentation in references/ loaded on demand\nasset — templates, images, fonts in assets/ used in output\nagents — platform UI metadata (e.g., Codex's agents/openai.yaml)\n\nFor files that cannot safely carry YAML frontmatter (binary files and strict-format files such as .json or executable .sh), the manifest tracks their version and its version field is authoritative.\n\nSKILL.md frontmatter constraint: The Agent Skills open standard (agentskills.io) requires name and description. Different platforms enforce different rules about additional fields:\n\nPlatform\tAllowed SKILL.md frontmatter\nagentskills.io spec\tname, description, license, metadata, compatibility, allowed-tools\nClaude Chat / Settings UI\tSame as spec. Claude's settings importer rejects unrecognized fields.\nClaude Code\tSpec fields plus extensions: disable-model-invocation, user-invocable, context, agent, model, hooks, argument-hint. These are Claude Code features, not part of the base spec.\nClaude API\tSkills uploaded via /v1/skills. Validates name and description. Supports metadata.\nGemini CLI (Google)\tname and description only. Extra fields not officially supported.\nCodex (OpenAI)\tname and description only. Extra fields rejected.\nGitHub Copilot / VS Code\tFollows agentskills.io spec.\nCursor, Roo Code, Junie, others\tFollows agentskills.io spec. See agentskills.io for the full adopter list (30+).\n\nFor maximum portability, keep SKILL.md frontmatter to name and description only. If the canonical bundle needs attribution or visible SKILL.md metadata, use the spec's metadata field there and generate a derived minimal copy for strict platforms:\n\n---\nname: my-skill\ndescription: What the skill does.\nmetadata:\n skill_bundle: my-skill\n file_role: skill\n version: 3\n version_date: 2026-02-10\n previous_version: 2\n change_summary: >\n Added Phase 6 validation step.\n---\n\n\nIf targeting Codex or other strict platforms directly, omit metadata from SKILL.md entirely. The manifest tracks SKILL.md's version either way, so no version information is lost.\n\nNote on spec support: The agentskills.io spec formally supports metadata as an arbitrary key-value map, with version shown as an example use. This means the metadata.version approach is now spec-blessed, not a Claude-only extension. However, the spec's version is a static label — it does not address staleness tracking, changelogs, or bundle integrity. Prefer manifest-based tracking as the default and use metadata only when you need version info visible in the file itself.\n\nManifest\n\nThe manifest is a YAML file named MANIFEST.yaml at the root of the skill bundle directory — the same level as SKILL.md. When the bundle is packaged as a .skill ZIP, the manifest lives inside the ZIP. It is the single source of truth for what the bundle contains.\n\nbundle: my-skill\nbundle_version: 5.1.0\nbundle_date: 2026-02-10\ndescription: >\n Skill for generating professional documents from source material\n and user briefs. Handles research, structuring, and formatting.\n\ncompatibility:\n designed_for:\n surfaces:\n - chat\n - cli\n - ide\n capabilities:\n - minimal SKILL.md frontmatter\n - local filesystem access\n - optional git workflow\n tested_on:\n - platform: Anthropic Claude\n model: Claude Opus 4.6\n surface: Chat\n status: pass\n date: 2026-02-10\n - platform: Anthropic Claude\n model: Claude Sonnet 4.5\n surface: Chat\n status: partial\n date: 2026-02-09\n notes: Misses staleness detection on complex bundles\n spec_version: agentskills.io/1.0\n frontmatter_mode: minimal\n # minimal = name + description only (Codex, Gemini CLI, max portability)\n # metadata = includes metadata block (any platform supporting the spec's metadata field)\n\ndependencies: []\n # List skill names this bundle depends on. Omit or leave empty if none.\n\ndeployments:\n api:\n version: 1759178010641129\n workspace: docs-prod\n claude:\n scope: user\n perplexity:\n package_format: zip\n\nfiles:\n - path: SKILL.md\n role: skill\n version: 5\n hash: sha256:abc123...\n note: Canonical skill definition\n\n - path: evals.json\n role: evals\n version: 3\n hash: sha256:def456...\n note: 7 evals including real-content synthesis\n\n - path: scripts/generate.js\n role: script\n version: 4\n hash: sha256:ghi789...\n note: Generation script for eval 3\n\n - path: outputs/eval3-output.pdf\n role: output\n version: 4\n hash: sha256:jkl012...\n note: Rendered eval 3 output, 10 pages, validated\n\n - path: sources/article-1.md\n role: source\n version: null\n hash: sha256:pqr678...\n note: Source article 1 (published)\n\nRules\n\nbundle_version uses semver (MAJOR.MINOR.PATCH). Bump MAJOR for breaking changes to the skill's model or interface, MINOR for new features or capabilities, PATCH for fixes and documentation updates. Per-file version fields remain integers — they are revision counters, not release identifiers.\n\nhash is sha256 of the file contents. This is how a new session verifies that the file it received matches what the manifest claims. Compute on save, verify on load.\n\ndeployments is optional. Use it to record deployed or installed copies of the same bundle when you want traceability across surfaces. Keep bundle_version as the author-side semver source of truth. Platform-native versions (for example API timestamps) stay in deployments, not in bundle_version.\n\nversion: null for source files. They are tracked for completeness but not versioned by this system.\n\nPaths are relative to the bundle root. No absolute paths.\n\nMANIFEST.yaml is not listed in files. Self-hashing is recursive. Treat the manifest as the bundle's control file and verify it via git, transport checksums, or the surrounding package when needed.\n\nThe .skill Package Format\n\nClaude's settings UI exports and imports skills as .skill files. These are standard ZIP archives containing a directory named after the skill. The versioning artifacts (MANIFEST.yaml, CHANGELOG.md, README.md) live inside this directory at the same level as SKILL.md:\n\nskill-name.skill (ZIP)\n└── skill-name/\n ├── SKILL.md\n ├── MANIFEST.yaml\n ├── CHANGELOG.md\n ├── README.md\n ├── assets/\n └── references/\n\n\nClaude's settings importer only looks for SKILL.md and the directory structure it expects (references, assets). It ignores files it doesn't recognize. This means the versioning artifacts travel safely inside the .skill ZIP without affecting import/export behavior.\n\nWhen bootstrapping or updating a bundle, always include the versioning artifacts in the .skill ZIP so they survive round-trips through Claude's settings UI.\n\nSome uploaders only accept .zip or .md. In those cases, rename the archive from .skill to .zip without changing its contents.\n\nThe spec recommends keeping SKILL.md under 500 lines and moving detailed reference material to separate files. Provenance artifacts fit naturally into that model: MANIFEST.yaml and CHANGELOG.md are load-on-demand resources, not always-loaded instructions.\n\nClaude Code provides a ${CLAUDE_SKILL_DIR} variable for bundle-relative paths. Other platforms may not. Direct relative paths like ./validate.sh work when the working directory is the bundle root.\n\nThe .skill ZIP only carries the skill definition and its references. Bundles can still track evals, scripts, rendered outputs, and handoff notes outside the archive. The manifest remains the complete inventory, not just the package inventory.\n\nChangelog\n\nThe changelog is a file named CHANGELOG.md at the root of the skill bundle directory, alongside SKILL.md and MANIFEST.yaml. In the bundle, it carries recent history with newest entries at the top. If the canonical source lives in git, older entries can be archived in a repo-level changelog outside the bundle.\n\n# Changelog\n\n## 5.1.0 — 2026-02-10\n- SKILL.md: Rewrote Phase 5 layout rules. Removed per-section page breaks.\n Added content flow check and a standalone validation checklist.\n- evals.json: Not yet updated (stale, needs alignment).\n\n## 5.0.0 — 2026-02-09\n- SKILL.md: Reworked body flow rules and added an optional appendix.\n- evals.json: Eval 3 expectations updated for content flow.\n\nRules\n\nEach entry names every file that changed and what changed in it.\n\nFiles that are stale get called out. If SKILL.md changes but evals.json was not updated to match, the changelog says so. This prevents the silent drift that caused the v4/v5 confusion.\n\nEntries are human-written prose, not auto-generated diffs. The point is to communicate intent, not enumerate line changes. Git diffs are available when the bundle is in git.\n\nBundle changelogs can be trimmed. Keeping the last 5-15 entries in the bundle is reasonable if the source repository maintains a full append-only changelog elsewhere.\n\nSession Protocol\nOpening a session\n\nWhen a skill bundle is loaded into a new session:\n\nRead MANIFEST.yaml first.\nVerify all listed files are present. Report any missing files.\nFor files with hashes, verify hashes match. Flag mismatches. In local environments, users can run validate.sh before uploading for reliable hash verification without LLM computation.\nRead CHANGELOG.md to understand recent changes.\nCheck for staleness: if any file's version is lower than the bundle version, or if deployments clearly show a deployed copy behind the local bundle, flag it and ask the user whether it needs updating.\nIf MANIFEST.yaml is missing, treat the bundle as unversioned. Offer to create one by inventorying the files and asking the user for version context.\nSaving / closing a session\n\nWhen work is complete and files are being delivered:\n\nUpdate internal version headers for changed files that use them.\n\nUpdate MANIFEST.yaml with new versions and hashes for every changed versioned file, including manifest-only files. If the user deployed or reinstalled the skill this session, update any relevant deployments metadata too.\n\nAdd a new top entry to CHANGELOG.md.\n\nIf any versioned file was changed but another dependent file was not updated (e.g., SKILL.md changed but evals.json was not updated), note the staleness explicitly in the changelog entry.\n\nDeliver the full bundle to the user, or at minimum the changed files plus the updated MANIFEST.yaml and CHANGELOG.md.\n\nIf the user indicates the bundle is destined for a git repo, provide a ready-to-use commit message derived from the changelog entry. Format:\n\nskill-name MAJOR.MINOR.PATCH: one-line summary\n\n- file1.md: what changed\n- file2.json: what changed\n- Stale: file3.js (not updated this session)\n\n\nReturn the message inline by default. Only write a transient git_commit.txt file if the user explicitly asks for a file or if the environment makes file output materially more convenient.\n\nHandoff between sessions\n\nA handoff note is a snapshot of project state for the next session. It should include:\n\nCurrent bundle version\nWhat was accomplished this session\nWhat is stale and needs attention\nWhat the next session should do first\nAny decisions made that are not yet reflected in the files\nPer-file change summaries: for each file modified this session, a brief description of what changed (section added, field removed, logic rewritten, etc.). This is more granular than the changelog entry and helps the next session verify the work without re-reading every file.\n\nCreate a handoff note only when crossing a non-persistent boundary or when the user explicitly asks for one. In filesystem-native environments with a current manifest, changelog, and git history, it is usually unnecessary. When created, it replaces the previous handoff note; previous handoffs live in changelog history.\n\nConflict resolution\n\nWhen a session finds version conflicts (e.g., a file claims v5 but the manifest says v4, or two files claim different bundle versions):\n\nPresent the conflict to the user with the specific discrepancy.\nShow what each version claims via its change_summary.\nDefault recommendation: trust the most recent version_date.\nAlways ask the user for explicit confirmation before proceeding.\n\nNever silently resolve a version conflict. The whole point of this system is to make conflicts visible.\n\nCross-Surface and Cross-Platform Considerations\n\nTreat one skill as moving through three states:\n\nCanonical source bundle: The working copy in git or local storage. Keep MANIFEST.yaml and the active CHANGELOG.md here. This is the author-side source of truth. If you maintain a full archive in git, keep it at repo root or another repo-level path outside the bundle.\nStrict-platform install copy: A derived copy for Codex, Gemini CLI, Perplexity, or other loaders that only accept name and description. Strip the metadata block from SKILL.md, set frontmatter_mode: minimal, recompute hashes in that copy, and leave the canonical bundle unchanged unless you intentionally promote the derived copy.\nRegistry or settings package: A consumer package such as a .skill ZIP or ClawHub upload. It may omit development-only files, but its MANIFEST.yaml must describe exactly what the package contains. Update deployments only after a real publish, reinstall, or redeploy.\n\nSurface notes:\n\nClaude Chat: Stateless upload/download boundary. Verify on open and consider a handoff note.\nClaude Cowork / Claude Code / Claude Agent SDK: Persistent filesystem. The manifest and changelog live with the bundle.\nClaude API: Deployment versions live in deployments, not in bundle_version.\nOther agentskills clients: Unknown files are ignored safely. .agents/skills/ can act as a neutral install path.\n\nGeneral principle: the manifest and changelog stay authoritative, and transformed install or publish copies are derived artifacts, not silent edits to the canonical bundle.\n\nTrust and Audit\n\nUse the manifest, changelog, hashes, and optional deployment metadata to verify what belongs in the bundle, whether files still match their recorded state, what changed, and which installed or deployed copies may now be stale. If a bundle comes from an untrusted source, verify it first.\n\nFile Naming\n\nVersioned files use stable names without version numbers:\n\nSKILL.md (not SKILL_v5.md)\nevals.json (not evals_v3.json)\ngenerate.js (not generate-v4.js)\n\nThe version lives inside the file (via the header) and in the manifest, not in the filename. Version-numbered filenames are how we got into trouble in the first place.\n\nException: if a user's local storage requires version-in-filename for their workflow, the manifest is the tiebreaker for which version is canonical. Internal version identity must still match.\n\nBootstrap\n\nTo version an existing unversioned skill bundle:\n\nInventory all files present — read the directory structure or uploaded file list. Do not ask the user to list files; determine this yourself.\nAsk the user what version number to assign. If there's a handoff note or other context, propose a number based on the history.\nAdd internal version headers to files that can safely carry them and record manifest-only versions for strict-format files.\nGenerate MANIFEST.yaml with hashes.\nCreate CHANGELOG.md with a single entry summarizing known history.\nDeliver the versioned bundle.\n\nThis is a one-time operation per skill bundle.\n\nOrigin\n\nDeveloped by Snap Synapse. Canonical source: https://github.com/snapsynapse/skill-provenance" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/snapsynapse/skill-provenance", "publisherUrl": "https://clawhub.ai/snapsynapse/skill-provenance", "owner": "snapsynapse", "version": "4.7.2", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/skill-provenance", "downloadUrl": "https://openagent3.xyz/downloads/skill-provenance", "agentUrl": "https://openagent3.xyz/skills/skill-provenance/agent", "manifestUrl": "https://openagent3.xyz/skills/skill-provenance/agent.json", "briefUrl": "https://openagent3.xyz/skills/skill-provenance/agent.md" } }