From db012468a08a0ec1bc5a364b11eb75c3a5bf19b3 Mon Sep 17 00:00:00 2001 From: Jarvis Jr Hermes Date: Mon, 26 Oct 2026 10:22:35 +0000 Subject: [PATCH] fix: qualify Delivery sources and preserve compatibility --- README.md | 8 +++++--- SKILL.md | 15 +++++++++------ compatibility/documentation-docusaurus.md | 19 +++++++++++++++++++ references/drawio-source-diagrams.md | 2 +- scripts/validate_skill.py | 8 ++++++-- 5 files changed, 40 insertions(+), 12 deletions(-) create mode 100644 compatibility/documentation-docusaurus.md diff --git a/README.md b/README.md index 5d9ba5f..64432ca 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# documentation-docusaurus +# documentation-docusaurus-vssa VSSA-managed Hermes skill for the complete Docusaurus documentation lifecycle: @@ -13,8 +13,10 @@ VSSA-managed Hermes skill for the complete Docusaurus documentation lifecycle: - Gitea: - Branch: `main` -- Maintainer worktree: `/opt/data/documentation-docusaurus-skill` -- Runtime installation: `/opt/data/skills/productivity/documentation-docusaurus` → maintainer worktree +- Runtime package: `documentation-docusaurus-vssa` (complete repository package). +- Compatibility: install `compatibility/documentation-docusaurus.md` as `documentation-docusaurus/SKILL.md`; old callers still load this VSSA adoption. +- Generic owner: `documentation-docusaurus-global`, from the distinct `home-v1-skills-code-agent/documentation-docusaurus` repository. +- Repository URL and all VSSA-specific reference content remain independently maintained. ## Validate diff --git a/SKILL.md b/SKILL.md index 9732db9..5273411 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,5 +1,5 @@ --- -name: documentation-docusaurus +name: documentation-docusaurus-vssa description: > Opinionated Docusaurus v3 guidance using Diátaxis. Use when creating or restructuring documentation, writing MDX, configuring navigation or deployment, building evidence registries and local YAML data, @@ -11,7 +11,7 @@ description: > license: MIT metadata: author: workspace-skills-code-agent - version: "2.0" + version: "2.1" spec: agentskills.io/specification framework: Diátaxis hermes: @@ -28,12 +28,15 @@ compatibility: Designed for Docusaurus v3. Works with Cline, Claude Code, GitHub This VSSA-managed skill is maintained in Gitea at `https://gitea.lego-cloud.eu/vssa-v1-skills-code-agent/documentation-docusaurus`. -Treat repository `main` as the source of truth. The maintainer worktree is -`/opt/data/documentation-docusaurus-skill`, and the runtime installation is a symlink to that -worktree. For every reusable improvement: fetch and fast-forward, edit the repository package, +Treat repository `main` as the source of truth. Install the complete published package under `documentation-docusaurus-vssa`. +Install `compatibility/documentation-docusaurus.md` as the legacy +`documentation-docusaurus/SKILL.md` compatibility route; existing callers keep VSSA behavior. +Generic guidance instead loads `documentation-docusaurus-global` from +https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus. +Do not overwrite either source with the other. For every reusable improvement: fetch and fast-forward, edit the repository package, run `python3 scripts/validate_skill.py`, review the complete diff, commit and push, verify exact ref equality and authenticated remote readback, require the exact-SHA Gitea Actions task to succeed, and -then verify `skill_view(name='documentation-docusaurus')` loads the changed package. Never maintain a +then verify `skill_view(name='documentation-docusaurus-vssa')` loads the changed package. Never maintain a divergent runtime-only copy. This repository is an independent VSSA adoption. Upstream or project-specific skill repositories are diff --git a/compatibility/documentation-docusaurus.md b/compatibility/documentation-docusaurus.md new file mode 100644 index 0000000..0d9aaae --- /dev/null +++ b/compatibility/documentation-docusaurus.md @@ -0,0 +1,19 @@ +--- +name: documentation-docusaurus +description: Compatibility alias for the VSSA Docusaurus adoption. +version: 1.0.0 +license: MIT +metadata: + hermes: + related_skills: [documentation-docusaurus-vssa] +--- + +# VSSA Docusaurus compatibility route + +Load `documentation-docusaurus-vssa` before performing documentation work. +Its complete package is maintained at +https://gitea.lego-cloud.eu/vssa-v1-skills-code-agent/documentation-docusaurus. +For a legacy reference-file request, load the same relative reference path from +`documentation-docusaurus-vssa`. Do not substitute generic guidance for VSSA content. +Generic guidance has the distinct name `documentation-docusaurus-global` at +https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus. diff --git a/references/drawio-source-diagrams.md b/references/drawio-source-diagrams.md index cef9bad..4a76095 100644 --- a/references/drawio-source-diagrams.md +++ b/references/drawio-source-diagrams.md @@ -8,7 +8,7 @@ Use this workflow when a Docusaurus v3 site must render an editable Draw.io sour - Render that source directly in MDX; do not make a PNG/SVG export the only authoritative artifact. - Keep the source adjacent to, or in a clearly named diagram directory near, the page that consumes it. - Use the global `diagrams-drawio` skill to author and validate diagram content. -- Use this `documentation-docusaurus` skill to onboard and render the source in Docusaurus. +- Use this `documentation-docusaurus-vssa` skill to onboard and render the source in Docusaurus. Recommended layout: diff --git a/scripts/validate_skill.py b/scripts/validate_skill.py index cdb75c2..a6bab9f 100644 --- a/scripts/validate_skill.py +++ b/scripts/validate_skill.py @@ -10,8 +10,12 @@ assert text.startswith("---\n"), "SKILL.md must start with YAML frontmatter" parts = text.split("\n---\n", 1) assert len(parts) == 2 and parts[1].strip(), "frontmatter must close and body must be non-empty" frontmatter, body = parts -assert re.search(r"^name:\s*documentation-docusaurus\s*$", frontmatter, re.M), "wrong skill name" +assert re.search(r"^name:\s*documentation-docusaurus-vssa\s*$", frontmatter, re.M), "wrong skill name" assert "description:" in frontmatter, "missing description" +alias = (ROOT / "compatibility/documentation-docusaurus.md").read_text() +assert "name: documentation-docusaurus\n" in alias +assert "Load `documentation-docusaurus-vssa`" in alias +assert "documentation-docusaurus-global" in alias assert len(text) <= 100_000, "SKILL.md exceeds Hermes size limit" assert "## Authoritative repository" in body assert "## Gitea delivery gate" in body @@ -47,6 +51,6 @@ unreferenced = sorted(name for name in reference_names if name not in coverage_t assert not unreferenced, f"unreferenced support files: {unreferenced}" print( - f"OK skill=documentation-docusaurus chars={len(text)} " + f"OK skill=documentation-docusaurus-vssa chars={len(text)} " f"references={len(reference_names)} markdown_files={len(markdown_files)}" )