[codex] Polish briefprint skill docs

docs/agent-skill-installation.md

@@ -16,6 +16,15 @@ Last checked: 2026-07-04
 
 Community host commands below are examples to verify against the current host documentation before use. Prefer any current host option that installs the `skills/briefprint` subdirectory without copying the repository root.
 
+| Host | Install example | Drift risk | Required post-check |
+| --- | --- | --- | --- |
+| Gemini CLI | Use the current `gemini skills` subpath flow or copy the bundle to `.agents/skills/briefprint`. | Installer flags can change. | Verify the installed directory is `skills/briefprint`, not the repository root. |
+| Antigravity | `npx skills add dd3ok/briefprint`, then select only `briefprint` when prompted. | Interactive selection can copy too much if the root is selected. | Verify only `SKILL.md`, `agents/openai.yaml`, and `references/*.md` were installed. |
+| OpenClaw | Use the current OpenClaw installer for local `./skills/briefprint`, or copy the bundle to `.agents/skills/briefprint`. | Discovery paths vary by workspace and user scope. | Run the host's skills list/check command and verify the selected path. |
+| Hermes | Use the current Hermes single-path install for `dd3ok/briefprint/skills/briefprint`, or copy the bundle to `~/.hermes/skills/briefprint`. | GitHub path syntax can drift. | Verify only the lightweight bundle files are present. |
+
+Use the source links at the end of this document to confirm current host syntax before publishing or automating these examples.
+
 This repository has two different install surfaces:
 
 - Python package/runtime: installs `document_briefing_cache` code and templates.
@@ -89,66 +98,6 @@ cp -R skills/briefprint .claude/skills/briefprint
 
 For Claude API skill upload flows, zip a common root that contains this bundle, not the whole repository.
 
-## Gemini CLI
-
-Gemini CLI supports user and workspace skill directories, including interoperable `.agents/skills` locations. It also supports installing a skill from a Git repository subpath.
-
-Recommended installs:
-
-```bash
-gemini skills install https://github.com/dd3ok/briefprint.git --path skills/briefprint --scope user
-
-mkdir -p ~/.agents/skills
-cp -R skills/briefprint ~/.agents/skills/briefprint
-```
-
-## Antigravity
-
-Google describes Antigravity skills as lightweight, open-format agent extensions and points users to `npx skills add` for skill installations. Because installer flags vary by version, do not accept an install unless it selects the `briefprint` skill under `skills/briefprint`.
-
-Recommended install:
-
-```bash
-mkdir -p .agents/skills
-cp -R skills/briefprint .agents/skills/briefprint
-```
-
-Optional installer flow:
-
-```bash
-npx skills add dd3ok/briefprint
-```
-
-Use the interactive prompt to select only `briefprint`, then verify the installed directory contains only `SKILL.md`, `agents/openai.yaml`, and `references/*.md`.
-
-## OpenClaw
-
-OpenClaw discovers skills from workspace `skills`, project `.agents/skills`, personal `~/.agents/skills`, and managed `~/.openclaw/skills` locations.
-
-Recommended installs:
-
-```bash
-mkdir -p skills .agents/skills ~/.agents/skills
-cp -R skills/briefprint .agents/skills/briefprint
-
-openclaw skills install ./skills/briefprint --as briefprint
-```
-
-Run `openclaw skills list` or `openclaw skills check` after installation.
-
-## Hermes
-
-Hermes uses `~/.hermes/skills` for primary skill storage and supports Agent Skills repositories. It can install a single GitHub skill path.
-
-Recommended installs:
-
-```bash
-hermes skills install dd3ok/briefprint/skills/briefprint
-
-mkdir -p ~/.hermes/skills
-cp -R skills/briefprint ~/.hermes/skills/briefprint
-```
-
 ## Validation
 
 Local repository validation checks that the installable bundle stays small and does not include development-only directories:

skills/briefprint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: briefprint
-description: Use for supplied documents, notes, logs, tickets, reports, transcripts, JSON/XML/API payloads, or cached briefing state when the user asks to summarize, brief, digest, recap, or rerender them while reusing structured document summaries. Do not use for live research, source-code review/debugging, general writing, translation-only edits, simple Q&A, or analysis without cacheable document input.
+description: Use to summarize, brief, digest, recap, or rerender docs/notes/tickets/logs/reports/transcripts, JSON/XML/API, or cached briefing state. Not for live research, source-code review/debugging, general writing, translation-only, simple Q&A, or non-cacheable input.
 ---
 
 # Briefprint

tests/test_installable_skill_bundle.py

@@ -42,6 +42,7 @@ def test_installable_skill_bundle_frontmatter_and_references_are_portable():
     assert re.fullmatch(r"[a-z0-9-]{1,64}", name)
     assert description
     assert len(description) <= 1024
+    assert len(description) <= 260
 
     root_only_fragments = [
         "src/",
@@ -70,7 +71,6 @@ def test_agent_skill_installation_doc_covers_lightweight_vendor_paths():
     assert "Do not install the repository root" in doc
     assert "~/.codex/skills" not in doc
     assert "npx skills install" not in doc
-    assert "npx skills add" in doc
     for section in [
         "Verified surfaces",
         "Community-compatible notes",
@@ -83,6 +83,17 @@ def test_agent_skill_installation_doc_covers_lightweight_vendor_paths():
     for vendor in ["Codex", "Claude Code", "Gemini CLI", "Antigravity", "OpenClaw", "Hermes"]:
         assert vendor in doc
 
+    community_notes = doc.split("## Community-compatible notes", 1)[1].split("## Bundle Contents", 1)[0]
+    for vendor in ["Gemini CLI", "Antigravity", "OpenClaw", "Hermes"]:
+        assert vendor in community_notes
+        assert f"## {vendor}" not in doc
+    assert "skills/briefprint" in community_notes
+    assert "repository root" in community_notes
+    assert "verify" in community_notes.lower()
+    assert "SKILL.md" in community_notes
+    assert "agents/openai.yaml" in community_notes
+    assert "references/*.md" in community_notes
+
 
 def test_validate_skill_reports_missing_installable_skill_without_crashing(tmp_path):
     module = _load_validate_skill_module()

tests/test_skill_metadata.py

@@ -44,6 +44,25 @@ def test_skill_description_matches_supported_modes_and_boundary():
     skill = SKILL.read_text(encoding="utf-8")
 
     frontmatter = skill.split("---", 2)[1]
+    description = next(
+        line.split(":", 1)[1].strip().strip('"') for line in frontmatter.splitlines() if line.startswith("description:")
+    )
+    assert len(description) <= 260
+    description_lower = description.lower()
+    for term in ["summarize", "brief", "digest", "recap", "rerender", "cached briefing state"]:
+        assert term in description_lower
+    for input_kind in ["docs", "notes", "tickets", "logs", "reports", "transcripts", "json/xml/api"]:
+        assert input_kind in description_lower
+    for boundary in [
+        "live research",
+        "source-code review/debugging",
+        "general writing",
+        "translation-only",
+        "simple q&a",
+    ]:
+        assert boundary in description_lower
+    assert "cacheable" in description_lower
+    assert "input" in description_lower
     assert "compare" not in frontmatter
     assert "source-code review/debugging" in frontmatter
     assert "code-review notes or PR discussion documents" in skill