@vegastack/skills 0.1.0 → 0.2.0

package/skill/{vegastack-arch-guardian → arch-guardian}/refresh/sources.json

@@ -22,8 +22,8 @@
       "service": "EVE",
       "kind": "pinned-source-package",
       "pinnedVersion": "0.29.5",
-      "currentVersion": "0.31.2",
-      "versionCheckedAt": "2026-08-07T18:47:48.335Z",
+      "currentVersion": "0.31.3",
+      "versionCheckedAt": "2026-08-08T07:53:01.687Z",
       "commit": "8988139097d1e1a1f1aca9b2828e63408848fccf",
       "stability": "beta-protocol-critical",
       "thresholdDays": 14,
@@ -639,7 +639,7 @@
       "service": "Turborepo",
       "kind": "official-docs",
       "pinnedVersion": "2.5.6",
-      "currentVersion": "2.10.8",
+      "currentVersion": "2.10.9",
       "stability": "tooling",
       "thresholdDays": 30,
       "critical": false,
@@ -666,7 +666,7 @@
         "rule:PKG-002",
         "ref:topology-monorepo"
       ],
-      "versionCheckedAt": "2026-08-07T18:47:48.335Z"
+      "versionCheckedAt": "2026-08-08T07:53:01.687Z"
     },
     {
       "id": "FLUTTER-DOCS",
@@ -777,8 +777,8 @@
       "versionDetection": {
         "type": "http-hash-and-changelog"
       },
-      "retrievedAt": "2026-08-07T18:47:48.335Z",
-      "checksum": "a8e45e4fda04b32279f1a82bd0afa7380b70f738cc1b5ee42ab178945d7dd1fe",
+      "retrievedAt": "2026-08-08T07:53:01.687Z",
+      "checksum": "9d428c76f42eafa6cd895e29bc54cd7b2ba0fa067c63eef457d6cf1a519b1b71",
       "previousRetrievalChecksum": "d8117a391c5875a7b4d352a3f8b8b89ad12e6617a91038228f7279c732d0cd98",
       "topics": [
         "notifications",
@@ -1047,7 +1047,7 @@
       "service": "AI SDK",
       "kind": "official-docs-package",
       "pinnedVersion": "7.x",
-      "currentVersion": "7.0.57",
+      "currentVersion": "7.0.58",
       "stability": "model-library",
       "thresholdDays": 30,
       "critical": false,
@@ -1075,7 +1075,7 @@
         "rule:MODEL-001",
         "ref:models-observability"
       ],
-      "versionCheckedAt": "2026-08-07T18:47:48.335Z"
+      "versionCheckedAt": "2026-08-08T07:53:01.687Z"
     },
     {
       "id": "ANTHROPIC-MODELS",
@@ -1152,8 +1152,8 @@
         "ref:model-lifecycle",
         "ref:models-observability"
       ],
-      "checksum": "379866ba1eef7fa6ed14b14f7961fb3f58989e02dc1e54d12c4a8293d87667fd",
-      "retrievedAt": "2026-08-07T19:12:27.794Z"
+      "checksum": "5f2224358c1f3f47ba6cdd5e46b2d695a2c8bfcad93faedcab549290fcada1e6",
+      "retrievedAt": "2026-08-08T07:53:01.687Z"
     }
   ]
 }

package/skill/{vegastack-arch-guardian → arch-guardian}/scripts/refresh-evidence.mjs

@@ -13,7 +13,7 @@ const defaultRegistry = join(skillRoot, 'refresh', 'sources.json')
 const maximumBytes = 5 * 1024 * 1024
 // Every host referenced by refresh/sources.json must appear here; loadRegistry enforces the
 // consistency so the allowlist cannot silently drift from the registry.
-const approvedHosts = new Set(['ai-sdk.dev', 'ai.google.dev', 'api.flutter.dev', 'aws.amazon.com', 'better-auth.com', 'bun.sh', 'developer.apple.com', 'developers.cloudflare.com', 'developers.openai.com', 'docs.aws.amazon.com', 'docs.flutter.dev', 'firebase.google.com', 'git.postgresql.org', 'github.com', 'modal.com', 'modelcontextprotocol.io', 'nextjs.org', 'openbao.org', 'openid.github.io', 'opennext.js.org', 'opentelemetry.io', 'platform.claude.com', 'pub.dev', 'pypi.org', 'raw.githubusercontent.com', 'registry.npmjs.org', 'riverpod.dev', 'turborepo.dev', 'workflow-sdk.dev', 'www.cloudflare.com', 'www.npmjs.com', 'www.postgresql.org'])
+const approvedHosts = new Set(['agentskills.io', 'ai-sdk.dev', 'ai.google.dev', 'api.flutter.dev', 'aws.amazon.com', 'better-auth.com', 'bun.sh', 'code.claude.com', 'developer.apple.com', 'developers.cloudflare.com', 'developers.openai.com', 'docs.aws.amazon.com', 'docs.flutter.dev', 'firebase.google.com', 'git.postgresql.org', 'github.com', 'hermes-agent.nousresearch.com', 'learn.chatgpt.com', 'modal.com', 'modelcontextprotocol.io', 'nextjs.org', 'openbao.org', 'openid.github.io', 'opennext.js.org', 'opentelemetry.io', 'platform.claude.com', 'pub.dev', 'pypi.org', 'raw.githubusercontent.com', 'registry.npmjs.org', 'riverpod.dev', 'turborepo.dev', 'workflow-sdk.dev', 'www.cloudflare.com', 'www.npmjs.com', 'www.postgresql.org'])
 
 function flagValue(argv, flag) {
   const value = argv.shift()
@@ -309,6 +309,9 @@ export async function refreshEvidence(options) {
       Object.assign(source, update)
       report.acceptedBaselines.push({ id: source.id, ...update })
     }
+    // A manual-review flag raised earlier in this same run is satisfied by the acceptance that
+    // just refreshed the source's retrievedAt — it must not fail-close the run that fixed it.
+    for (const entry of report.manualVersionReview) if (baselineUpdates.get(entry.id)?.retrievedAt) { entry.due = false; entry.ageDays = 0 }
     await atomicJson(options.registry, registry)
   }
   await atomicJson(options.cache, cache)

package/skill/skill-maintainer/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: skill-maintainer
+description: Maintainer skill for the vegastack-skills repository itself. Use whenever working on this repo - creating or scaffolding a new skill, editing an existing skill (SKILL.md, references, refresh registry, tests), renaming, deprecating, or removing a skill, cutting a release or rolling one back, or checking cross-agent portability across Claude Code, Codex, Hermes, and the agentskills.io standard. Encodes the tri-harness standards (frontmatter policy, naming grammar, description and context budgets, install surfaces) and the per-skill contract every change under skills/ must satisfy. Load it before touching any file in this repo.
+---
+
+# VegaStack Skill Maintainer
+
+Maintenance skill for this repository. Every change under `skills/` must satisfy the per-skill contract and the tri-harness standards below. Obey them in your own edits; enforce them in review. When a rule here disagrees with `CONTRIBUTING.md` or `docs/policies/` at the repo root, those win — then fix this skill.
+
+## Operating rules
+
+1. Skill content lives only in `skills/<name>/`. Wiring lives outside it: the packaging allowlist in `packages/cli/scripts/sync-skill.mjs`, the root `README.md` skills table, and `CHANGELOG.md` (via changesets).
+2. Frontmatter is exactly two keys: `name` and `description`. The open spec also allows `license`, `compatibility`, and `metadata`, but this repo defaults to the minimal two; adding any other key is a policy exception needing maintainer sign-off.
+3. `name` must equal the directory name. Grammar: starts with a lowercase letter, then only lowercase letters, digits, and hyphens; no leading/trailing hyphen, no consecutive hyphens; at most 64 chars.
+4. `description`: at most 1024 chars, third person, states WHAT the skill does and WHEN to load it, trigger words front-loaded, no angle brackets. Never summarize the workflow in it — agents follow the summary and skip the body. Err slightly pushy: agents under-trigger.
+5. `SKILL.md` under 500 lines (target under 150) and roughly under 5k tokens. Detail goes to `references/`, executables to `scripts/`, templates to `assets/`. Relative links stay inside the skill, one level deep.
+6. No Claude-only body syntax anywhere in a skill: no dynamic command injection, no argument placeholders, no Claude environment-variable paths — the exact token list is in [standards](references/standards.md). Reference scripts as plain relative paths runnable from the skill directory.
+7. Never hand-edit checksums, versions, or timestamps in any `refresh/sources.json` — they must come from a refresh-runner run.
+8. Before finishing any change: `node packages/cli/scripts/validate-skill.mjs skills/<name>` and `bun test skills/<name>` (both from repo root) must pass.
+
+## Route progressively
+
+| Need | Read |
+|---|---|
+| tri-harness standards: discovery paths, frontmatter rules, context budgets, install surfaces, portability rules, unverified items | [standards](references/standards.md) |
+| release, rename, deprecate, rollback mechanics | [release ops](references/release-ops.md) |
+| this skill's own freshness contract | [REFRESH](refresh/REFRESH.md), [sources](refresh/sources.json) |
+| authoritative repo policy | `CONTRIBUTING.md`, `docs/policies/content-versioning.md`, `docs/policies/release-and-rollback.md` at the repo root |
+
+## Workflow: scaffold a new skill
+
+1. Create `skills/<name>/` with the full per-skill contract: `SKILL.md` (agent entry), `README.md` (repo-side walkthrough, never packaged), `references/`, `tests/` (bun tests, never packaged), `refresh/sources.json` + `refresh/REFRESH.md` (freshness contract), `agents/openai.yaml` (Codex interface metadata); `scripts/` and `assets/` only if the skill needs them.
+2. Write frontmatter and body per operating rules 2–6; the body routes to references, it does not inline them.
+3. Wire it in: add every packaged file to the allowlist in `packages/cli/scripts/sync-skill.mjs` (the build fails loudly on unlisted files); add a row to the root README skills table; add a changeset (a new skill is MINOR).
+4. The installer is multi-skill: every authored skill needs a packaging allowlist entry in packages/cli/scripts/sync-skill.mjs (the build fails loudly on unlisted files).
+5. Seed refresh baselines with the deterministic runner, never by hand — invocation in [REFRESH](refresh/REFRESH.md).
+6. Run the checks in operating rule 8.
+
+## Workflow: update or maintain
+
+- **Stable IDs are permanent.** Never renumber or reuse a rule ID; removing or renaming one is a MAJOR content change (`docs/policies/content-versioning.md`). New rules/references are MINOR; weakening a MUST is MAJOR; factual refreshes (pins, URLs, checksums) are PATCH.
+- **Tag volatile claims.** Any sentence carrying a vendor version, mechanism name, or numeric budget gets a source marker comment mapping to an ID in that skill's `refresh/sources.json`, and the registry entry's `affected` list must name the reference it lives in. Untagged volatile facts rot silently.
+- **Description budgets.** Stay within 1024 chars and keep triggers in the first sentence: Codex truncates its skill list at 2% of the context window / 8,000 chars, Claude Code truncates a skill's always-loaded listing at 1,536 chars — the tail of a long description is the first thing lost.
+- **Packaged-file changes.** Any add/remove/rename of a packaged file must update the `sync-skill.mjs` allowlist in the same PR.
+
+## Workflow: rename, deprecate, or remove
+
+Full playbook in [release ops](references/release-ops.md). Short form: a rename changes the directory and the frontmatter `name` in the same commit (they must stay equal), updates allowlist + root README table + CHANGELOG, and is MAJOR. Deprecation is announced in README/CHANGELOG before removal. Removal deletes the tree, unwires it, and is MAJOR.
+
+## Workflow: release
+
+Changeset lands with the PR → maintainer runs `bunx changeset version`, `bun install`, commits → tags `v<version>` → tag-driven pipeline runs check, tag↔version guard, npm trusted publishing, SBOM, GitHub release. Two decoupled version identities — **package version** (npm, changesets) and **foundation version** (content contract for deployed profiles) — must never be conflated; bumping the package must never invalidate a deployed profile. Rollback is roll-forward (publish previous-good as a new patch) plus `npm deprecate` of the bad version; unpublish only within 72 hours and only in addition. Details: [release ops](references/release-ops.md).
+
+## Workflow: portability check
+
+Run this checklist before merging any skill change; per-harness detail in [standards](references/standards.md).
+
+- [ ] Frontmatter keys exactly `name` + `description`, values within limits (rules 2–4).
+- [ ] `name` equals the directory name.
+- [ ] Description has no angle brackets and triggers front-loaded.
+- [ ] `SKILL.md` under 500 lines; relative links resolve and stay inside the skill.
+- [ ] No Claude-only body syntax (token list in standards).
+- [ ] `agents/openai.yaml` present for Codex; extra files are safely ignored by the other harnesses.
+- [ ] Install surfaces respected: Claude Code `.claude/skills` (project) / `~/.claude/skills` (global); Codex `.agents/skills` (project and global); Hermes `~/.hermes/skills` **global only** — never assume Hermes project-level discovery.
+- [ ] `node packages/cli/scripts/validate-skill.mjs skills/<name>` and `bun test skills/<name>` pass.
+
+## Hard limits
+
+| Limit | Value |
+|---|---|
+| `name` | ≤ 64 chars, lowercase letter first, then `[a-z0-9-]`, no consecutive hyphens, equals directory name |
+| `description` | 1–1024 chars, no angle brackets |
+| `SKILL.md` | under 500 lines / ~5k tokens; target under 150 lines |
+| Claude Code listing | name + description truncated at 1,536 chars per skill |
+| Claude Code body | first 5,000 tokens persist across compaction; 25,000-token shared skills budget |
+| Codex skill list | 2% of context window / 8,000 chars — descriptions shortened first |
+| Hermes skills_list | ~3k tokens |
+
+These mirror marked sentences in [standards](references/standards.md); update both in the same PR when a source changes.

package/skill/skill-maintainer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "VegaStack Skill Maintainer"
+  short_description: "Maintain vegastack-skills skills to tri-harness standards"
+  default_prompt: "Use $skill-maintainer to make this vegastack-skills change satisfy the per-skill contract and tri-harness standards."

package/skill/skill-maintainer/references/release-ops.md

@@ -0,0 +1,63 @@
+# Release, rename, and rollback operations
+
+Condensed operational playbook. The authoritative policies live at the repo root — `docs/policies/release-and-rollback.md` and `docs/policies/content-versioning.md` — and this file must never contradict them; when in doubt, they win.
+
+## Semver for skill content
+
+Consumers depend on rule IDs and rule strength, not an API surface.
+
+| Bump | Content change |
+|---|---|
+| MAJOR | Removing or renaming a rule ID (IDs are stable and permanent — never renumber or reuse). Changing a `MUST`/`MUST NOT` so it permits something previously forbidden. Removing or renaming a skill. |
+| MINOR | New rules or rule IDs. New references or reference sections. New skill. Loosening ceremony without weakening a `MUST`. Tightening a `SHOULD` to a `MUST`. |
+| PATCH | Factual refreshes: version pins, vendor mechanism names, URLs, registry checksums. Typos and non-normative wording. Test/fixture-only changes. |
+
+Installer/CLI changes follow ordinary semver on the same package version; a release takes the highest bump either side requires.
+
+## Two version identities — never conflate
+
+| Identity | Lives in | Governs |
+|---|---|---|
+| Package version | `packages/cli/package.json` (changesets) | npm releases of installer + content snapshot |
+| Foundation version | profile schema const, `profile-tool.mjs` default, `foundation-compatibility.json` | the profile/schema contract deployed `.vegastack/architecture` profiles validate against |
+
+- Bumping the **package** (even MAJOR) must never invalidate a deployed profile — profiles bind to the foundation version.
+- Bumping the **foundation** version is a content-contract event: it requires a compatibility entry describing how existing baselines are treated, and at minimum a MINOR package release.
+- Each identity has one source of truth; never introduce additional copies of either number.
+
+## Release flow (tag-driven)
+
+1. Every PR that changes released behavior lands with a changeset (`bunx changeset`) whose bump follows the table above.
+2. Maintainer, at release time: `bunx changeset version` (applies changesets to `packages/cli/package.json` and the changelog), then `bun install` so `bun.lock` does not go stale, commit. Root `CHANGELOG.md` gets a human-readable entry for every release.
+3. Tag the release commit `v<version>`, push the tag.
+4. The release workflow runs on the tag: `bun run check`, tag↔version guard, `npm publish` via trusted publishing (OIDC, token-free, provenance by default; idempotently skipped if already on the registry), SBOM, GitHub release. Never pass `--provenance` explicitly — it conflicts with trusted-publishing config.
+
+Contributors do not bump versions in PRs; releases are maintainer-driven.
+
+## Rollback
+
+`npm unpublish` is limited to 72 hours and breaks pinned consumers — it is not the rollback mechanism.
+
+1. **Roll forward:** revert the offending commits on `main`, changeset, tag, release the previous known-good content as a **new patch version**.
+2. **Deprecate the bad version:** `npm deprecate @vegastack/skills@<bad> "Broken — use <new>"`.
+3. Unpublish only if the bad version leaked secrets or is actively harmful, still within 72 hours, and always *in addition to* steps 1–2, never instead.
+
+## Rename a skill
+
+Derived from the stable-ID logic in content-versioning (skill names are consumer-facing identifiers like rule IDs):
+
+1. Rename the directory and the frontmatter `name` in the same commit — they must always stay equal.
+2. Update every wiring point in the same PR: the packaging allowlist in `packages/cli/scripts/sync-skill.mjs`, the root README skills table row, and any cross-skill or docs links.
+3. Changeset: MAJOR. Note the migration in `CHANGELOG.md`: copies installed under the old name are orphaned, and installer operations addressed to the old name stop resolving once the shipped manifest no longer knows it.
+4. Registry source IDs inside `refresh/sources.json` are skill-internal and unaffected, but every `affected` ref must still resolve to a real reference in the renamed tree.
+5. Re-run `node packages/cli/scripts/validate-skill.mjs skills/<new-name>` and the skill's tests — name/directory equality is validated.
+
+## Deprecate / remove a skill
+
+1. Announce deprecation in the root README table and `CHANGELOG.md` at least one release before removal when practical.
+2. Removal: delete `skills/<name>/`, remove its allowlist entries and README row, MAJOR changeset with migration notes.
+3. Removing a skill in a new MAJOR does **not** deprecate previously published package versions — `npm deprecate` only versions that are themselves broken.
+
+## Refresh branches
+
+Branches named `refresh/**` are reserved for the automated freshness loop and are CI-restricted to `skills/*/refresh/` and `skills/*/references/foundation-compatibility.json`. Human content changes go on normal branches. Never hand-edit checksums/versions/timestamps anywhere — CI re-fetches claimed baselines, so hand-edited values cannot merge.

package/skill/skill-maintainer/references/standards.md

@@ -0,0 +1,92 @@
+# Tri-harness skill standards
+
+The complete standards reference for skills in this repository, covering the three target harnesses — Claude Code, Codex, Hermes — and the agentskills.io open standard they converge on. Verified 2026-08-08.
+
+Sentences carrying volatile vendor facts end with an HTML `source:` comment naming a registry ID; each ID maps to an entry in [sources.json](../refresh/sources.json). When a source changes, the marked sentences are the edit surface — see [REFRESH.md](../refresh/REFRESH.md). Items flagged **UNVERIFIED** must never be asserted as fact in skill content or reviews.
+
+## agentskills.io open standard
+
+Source: https://agentskills.io/specification. Reference validator: `skills-ref validate` from github.com/agentskills/agentskills. <!-- source: AGENTSKILLS-SPEC -->
+
+- Directory layout: `skill-name/SKILL.md` required; optional `scripts/`, `references/`, `assets/`. <!-- source: AGENTSKILLS-SPEC -->
+- Frontmatter — the spec defines exactly six fields: <!-- source: AGENTSKILLS-SPEC -->
+  - `name` (required): 1–64 chars, `[a-z0-9-]` only, no leading/trailing hyphen, no consecutive hyphens, must match the parent directory name. <!-- source: AGENTSKILLS-SPEC -->
+  - `description` (required): 1–1024 chars, what + when, keyword-rich. <!-- source: AGENTSKILLS-SPEC -->
+  - `license` (optional): short string or bundled-file reference. <!-- source: AGENTSKILLS-SPEC -->
+  - `compatibility` (optional): 1–500 chars, environment requirements only. <!-- source: AGENTSKILLS-SPEC -->
+  - `metadata` (optional): string→string map. <!-- source: AGENTSKILLS-SPEC -->
+  - `allowed-tools` (optional): space-separated string; experimental, support varies across harnesses. <!-- source: AGENTSKILLS-SPEC -->
+- Progressive disclosure: metadata costs ~100 tokens at startup; SKILL.md body should stay under 5,000 tokens (under 500 lines); bundled resources load on demand; relative file references one level deep. <!-- source: AGENTSKILLS-SPEC -->
+- The spec's own version identifier: **UNVERIFIED** — do not cite a spec version number.
+
+## Claude Code
+
+Source: https://code.claude.com/docs/en/skills. <!-- source: CLAUDE-CODE-SKILLS -->
+
+- Discovery: project `.claude/skills/<name>/SKILL.md`, loaded from the start directory and every parent up to the repo root; personal `~/.claude/skills/`; enterprise via managed settings; nested `<subdir>/.claude/skills/` lazy-loaded; plugin `<plugin>/skills/`. Precedence: enterprise > personal > project. Symlinks are followed; skill changes are detected live mid-session. <!-- source: CLAUDE-CODE-SKILLS -->
+- Frontmatter: all fields optional in Claude Code itself (directory name is the command name; description recommended). It accepts an extended set beyond the spec six — `when_to_use`, `argument-hint`, `arguments`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `disallowed-tools`, `model`, `effort`, `context` (fork), `agent`, `background`, `hooks`, `paths`, `shell`, plus `license`/`compatibility`/`metadata` (accepted but not acted on). <!-- source: CLAUDE-CODE-SKILLS -->
+- **Packaging trap:** claude.ai uploads, the Skills API, and `package_skill.py` hard-error on any key outside the spec six (`name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`) — a skill that works in Claude Code can still be unpackageable. <!-- source: CLAUDE-CODE-SKILLS -->
+- Context budgets: each skill's `description` (+`when_to_use`) is always in context, truncated at 1,536 chars combined per skill; the body loads on invocation and persists — the first 5,000 tokens are re-attached after compaction, within a 25,000-token budget shared across skills. <!-- source: CLAUDE-CODE-SKILLS -->
+- Invocation: implicit matching on description, or direct `/skill-name`. `allowed-tools` is a per-turn permission pre-grant only, not a sandbox. <!-- source: CLAUDE-CODE-SKILLS -->
+- Claude-only body features — **never use in this repo's skills** (broken or dead weight elsewhere): <!-- source: CLAUDE-CODE-SKILLS -->
+  - `` !`cmd` `` dynamic command-output injection
+  - `$ARGUMENTS`, `$0`, `$name` argument placeholders
+  - `${CLAUDE_SKILL_DIR}`, `${CLAUDE_PROJECT_DIR}` environment paths
+- 2026 changes: commands and skills merged; `context: fork` subagents; skill-level hooks; `paths` glob gating; `skillOverrides`; skills-dir plugins; bundled skills. <!-- source: CLAUDE-CODE-SKILLS -->
+
+## Codex (OpenAI)
+
+Source: https://developers.openai.com/codex/skills (canonical content at learn.chatgpt.com/docs/build-skills.md). <!-- source: CODEX-SKILLS -->
+
+- Discovery order: `$CWD/.agents/skills` → parent directories' `.agents/skills` within a git repo → `$REPO_ROOT/.agents/skills` → `$HOME/.agents/skills` → `/etc/codex/skills` → bundled. Symlinks followed. <!-- source: CODEX-SKILLS -->
+- Legacy `~/.codex/skills` discovery: **UNVERIFIED** — no longer documented; do not rely on it.
+- Frontmatter: `name` + `description` required; same SKILL.md format as the spec. <!-- source: CODEX-SKILLS -->
+- Unknown frontmatter keys: officially undocumented; community evidence says ignored — **UNVERIFIED** officially.
+- Optional per-skill `agents/openai.yaml`: <!-- source: CODEX-SKILLS -->
+  - `interface`: `display_name`, `short_description`, `icon_small`, `icon_large`, `brand_color`, `default_prompt`
+  - `policy`: `allow_implicit_invocation: false` (default true)
+  - `dependencies`: `tools: [{type: "mcp", value: "..."}]`
+- Invocation: `$` mention, `/skills` list, implicit matching on description. The skill list is capped at 2% of the context window / 8,000 chars — descriptions are shortened first, so front-load trigger words. <!-- source: CODEX-SKILLS -->
+
+## Hermes (Nous Research)
+
+Source: https://hermes-agent.nousresearch.com/docs/user-guide/features/skills. <!-- source: HERMES-SKILLS -->
+
+- Hermes Agent is Nous Research's open agent harness (github.com/NousResearch/hermes-agent; CLI + desktop + messengers; v0.9.0 Apr 2026), explicitly compatible with the agentskills.io standard. <!-- source: HERMES-SKILLS -->
+- Discovery: a single global directory `~/.hermes/skills/` — **no project-level discovery at all**. Extra directories only via `~/.hermes/config.yaml` under `skills.external_dirs` (e.g. `[~/.agents/skills]`). `hermes skills install <source>` installs from hubs/URLs into the global directory after a security scan. <!-- source: HERMES-SKILLS -->
+- Frontmatter: `name` + `description` required; optional Hermes fields: `version`, `platforms` (macos, linux), `required_environment_variables`, `requires_toolsets`, `fallback_for_toolsets`, `metadata.hermes.{tags, category, config}`. Name pattern `^[a-z][a-z0-9_-]*$` — must start with a letter (underscores allowed by Hermes but not by the spec; use hyphens). <!-- source: HERMES-SKILLS -->
+- Unknown-key handling, and treatment of `allowed-tools`/`license`/`compatibility`: **UNVERIFIED** (presumed ignored; no error reports).
+- Triggering: every skill becomes a slash command (`/name args`, chainable); model-side progressive disclosure via `skills_list()` (~3k tokens) then `skill_view(name)`. `/learn` auto-authors SKILL.md. <!-- source: HERMES-SKILLS -->
+
+## Install surfaces
+
+| Harness | Project install | Global install | Notes |
+|---|---|---|---|
+| Claude Code | `.claude/skills/` | `~/.claude/skills/` | parents scanned to repo root; nested dirs lazy-loaded <!-- source: CLAUDE-CODE-SKILLS --> |
+| Codex | `.agents/skills/` | `~/.agents/skills/` | also `/etc/codex/skills` and bundled <!-- source: CODEX-SKILLS --> |
+| Hermes | — none | `~/.hermes/skills/` | **global only**; extension only via `skills.external_dirs` config <!-- source: HERMES-SKILLS --> |
+
+Installer implication: the `@vegastack/skills` installer must treat Hermes as global-only — a "project install" for Hermes does not exist.
+
+## Portability rules (this repo's policy)
+
+One authored tree, three harnesses. Every skill in `skills/` follows all seven:
+
+1. **Frontmatter:** only `name` + `description` (spec also allows `license`, `compatibility`, `metadata` — off by default here). Never depend on `allowed-tools`. No Claude-only keys: they break claude.ai packaging and are dead weight elsewhere.
+2. **Name:** equals the directory name; grammar intersection across harnesses: starts with a lowercase letter, then `[a-z0-9-]`, no consecutive hyphens, no underscores, ≤ 64 chars.
+3. **Description:** ≤ 1024 chars, trigger words front-loaded (Codex 2%/8,000-char list budget; Claude Code 1,536-char per-skill listing truncation).
+4. **Body syntax:** no Claude-only tokens (list above); scripts referenced as plain relative paths runnable from the skill directory; relative links one level deep.
+5. **Size:** SKILL.md under 500 lines / under 5k tokens; detail in `references/`, executables in `scripts/`, templates in `assets/`.
+6. **Extra files:** `agents/openai.yaml` is safe to ship — Claude Code and Hermes ignore unknown files.
+7. **Per-harness metadata** that must survive claude.ai packaging goes under `metadata:` with namespaced keys (e.g. `metadata.hermes.*`).
+
+Repo enforcement: `packages/cli/scripts/validate-skill.mjs` (run by `bun run check`) accepts exactly the spec six (`name`, `description`, `license`, `compatibility`, `allowed-tools`, `metadata`) and rejects everything else, enforces the full name grammar (lowercase-letter start, no consecutive hyphens, ≤64 chars, name equals the skill directory name), and rejects empty or over-length descriptions and angle brackets. Policy (rule 1) is stricter than the validator; the minimal two keys are the default.
+
+## UNVERIFIED register
+
+Do not assert any of these; if one becomes load-bearing, verify against the live source first and move it into a marked sentence:
+
+- agentskills.io spec version identifier.
+- Codex official unknown-frontmatter-key behavior (community: ignored).
+- Codex legacy `~/.codex/skills` discovery.
+- Hermes unknown-key handling and its treatment of `allowed-tools`/`license`/`compatibility`.

package/skill/skill-maintainer/refresh/REFRESH.md

@@ -0,0 +1,40 @@
+# Refresh contract — skill-maintainer
+
+Instructions for the scheduled refresh agent (and any human running a manual refresh). This file, together with `sources.json`, is the complete freshness contract for this skill.
+
+## What this skill claims
+
+- **Durable content** (`SKILL.md` workflows and operating rules, `references/release-ops.md`): repo process, derived from `docs/policies/*` — the refresh agent NEVER edits these. If a policy doc changes, that is a normal human PR, not a refresh.
+- **Mechanism-coupled claims**: sentences marked `<!-- source: SOURCE-ID -->` inside `references/standards.md`. These carry the tri-harness standards — discovery paths, frontmatter rules, numeric context budgets, install surfaces. They are the compliance basis of every skill in this repo, so **all standards changes are semantic drift requiring a human-reviewed PR**: the agent may propose edits to marked sentences only, in the same PR as the registry update that evidences the change, and a maintainer must review before merge. The hard-limits table in `SKILL.md` mirrors several marked sentences; update it in the same PR (this is the one sanctioned SKILL.md touch, and only when a mirrored number changed).
+- **Volatile layer** (the only file the agent edits freely): `refresh/sources.json` — the source registry and staleness snapshot (checksums, retrieval times).
+
+## How to refresh
+
+The deterministic runner is repo-shared and hosted in arch-guardian for now. Run from the repo root:
+
+1. **Deterministic pass first** (no LLM judgment):
+   `node skills/arch-guardian/scripts/refresh-evidence.mjs --registry skills/skill-maintainer/refresh/sources.json`
+   drift/stale/unavailable results are the work-list. Exit 1 with a critical entry means fail-closed: the run must not be silently skipped. All four sources here are critical.
+2. **Accept verified changes** in the same code path:
+   `node skills/arch-guardian/scripts/refresh-evidence.mjs --registry skills/skill-maintainer/refresh/sources.json --accept-baselines`
+   This writes registry, cache, and drift report together — never hand-edit checksums, versions, or timestamps; they must always come from a run. Baselines are runner-seeded; when a new source is added or a verified change is accepted, this accept-baselines invocation is the only sanctioned way to update them.
+3. **Semantic verification** for every source the deterministic pass flagged: read the changed page (fetch the registry URL), decide whether any `<!-- source: X -->` marked sentence in `references/standards.md` (or the mirrored SKILL.md hard-limits row) is now wrong, and propose the minimal edit. Unlike version-pin registries, checksum drift here is presumed meaningful until a human reads the diff — these pages define the standards themselves. Editorial churn may be accepted silently only after that read.
+4. **One PR per refresh**, branch `refresh/<date>`, force-updating the standing refresh branch if last week's PR is unmerged (never stack duplicate PRs). PR body lists: each changed source, old→new checksum, links to the evidence, and which marked sentences changed and why. A maintainer review is mandatory before merge.
+5. Changes to durable content, workflows, tests, or anything outside `refresh/` and marked sentences are out of scope for a refresh PR — CI enforces this (refresh-guard workflow).
+
+## Cadence and thresholds
+
+Weekly scheduled run. Every `thresholdDays` in `sources.json` is ≥ 14 (2× cadence) so one missed run never breaches a threshold.
+
+## What counts as drift worth a PR
+
+- Any text-scope checksum change on any of the four sources → read the page; if a discovery path, frontmatter rule, numeric budget, or install surface changed, propose the marked-sentence edit and flag it prominently — downstream, every skill in `skills/` may need re-checking against the new standard (that re-check is a separate human task, never part of the refresh PR).
+- A source page moves to an UNVERIFIED area (e.g. a documented path disappears) → move the claim into the UNVERIFIED register in `references/standards.md` rather than asserting the old fact.
+- A critical source is unavailable or a redirect leaves the approved host set → investigate immediately; host changes require a deliberate `approvedHosts` update in the shared runner (out of refresh-PR scope — open an issue).
+
+## Never
+
+- Never edit unmarked sentences, workflows, or `references/release-ops.md`.
+- Never hand-write checksum/version/timestamp values.
+- Never merge a standards change without human review — this registry has no auto-acceptable semantic drift.
+- Never archive third-party documentation bodies in this repo (claim metadata, URLs, hashes, and concise excerpts only).

package/skill/skill-maintainer/refresh/sources.json

@@ -0,0 +1,103 @@
+{
+  "schemaVersion": 1,
+  "policy": {
+    "criticalTopics": [
+      "skills-standard"
+    ],
+    "defaultChecksumScope": "html-text-v1",
+    "offline": "Use cached metadata only; fail closed when a critical entry is missing or older than thresholdDays.",
+    "drift": "All four sources are the compliance basis for this skill: any drift requires reading the changed page and a human-reviewed PR updating the marked sentences in references/standards.md (and the mirrored hard-limits table in SKILL.md); never auto-apply.",
+    "copyright": "Store claim metadata, URLs, hashes, headers, and concise excerpts only; never archive whole third-party documentation corpora.",
+    "cadence": "weekly automated refresh; thresholdDays must be >= 14 (2x cadence) so a single missed run never breaches a threshold"
+  },
+  "sources": [
+    {
+      "id": "AGENTSKILLS-SPEC",
+      "service": "agentskills.io specification",
+      "kind": "official-spec",
+      "stability": "open-standard",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://agentskills.io/specification"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skills-standard"
+      ],
+      "affected": [
+        "ref:standards"
+      ],
+      "checksum": "1aecfc21328fcf51b456615477d7aebfa05b779c56d75c7721c4fd5f969af8f7",
+      "retrievedAt": "2026-08-08T07:52:08.251Z"
+    },
+    {
+      "id": "CLAUDE-CODE-SKILLS",
+      "service": "Claude Code skills documentation",
+      "kind": "official-docs",
+      "stability": "vendor-harness",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://code.claude.com/docs/en/skills"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skills-standard"
+      ],
+      "affected": [
+        "ref:standards"
+      ],
+      "checksum": "a2651c4f1a7aa43978c549c9f376c47b738ac53532fecc8168aee0d3b796469a",
+      "retrievedAt": "2026-08-08T07:52:08.251Z"
+    },
+    {
+      "id": "CODEX-SKILLS",
+      "service": "Codex skills documentation",
+      "kind": "official-docs",
+      "stability": "vendor-harness",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://developers.openai.com/codex/skills"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skills-standard"
+      ],
+      "affected": [
+        "ref:standards"
+      ],
+      "checksum": "b7667a87600436ae5d70e414a2a0fcb207e11c8ffdb7a28d93637980f3ff565d",
+      "retrievedAt": "2026-08-08T07:52:08.251Z"
+    },
+    {
+      "id": "HERMES-SKILLS",
+      "service": "Hermes Agent skills documentation",
+      "kind": "official-docs",
+      "stability": "vendor-harness",
+      "thresholdDays": 14,
+      "critical": true,
+      "urls": {
+        "primary": "https://hermes-agent.nousresearch.com/docs/user-guide/features/skills"
+      },
+      "versionDetection": {
+        "type": "manual-review"
+      },
+      "topics": [
+        "skills-standard"
+      ],
+      "affected": [
+        "ref:standards"
+      ],
+      "checksum": "c4ed10a90e9303adb7a80aa5531ea92a1debbe6c4edff588199b123429065893",
+      "retrievedAt": "2026-08-08T07:52:08.251Z"
+    }
+  ]
+}