GHX Skill

ghx is an enhanced reliability layer on top of gh, used by higher-level skills. It standardizes common GitHub operations and prevents common agent mistakes (especially shell escaping and multi-line payload issues).

It provides two capabilities:

• Context collection with a stable artifact manifest
• Publishing for PR/review/comment workflows

Environment Variables

• GITHUB_OUTPUT_DIR: artifact directory (caller-provided; defaults to a temp dir when unset)
• GITHUB_CONTEXT_DIR: context directory (default ${GITHUB_OUTPUT_DIR}/github-context)
• GITHUB_TOKEN / GH_TOKEN: token used by gh
• DRY_RUN: preview mode for publish commands (true|false)

Commands

Use scripts/ghx.sh as the entrypoint.

Context collection

bash
1scripts/ghx.sh context collect holon-run/holon#123
2scripts/ghx.sh context collect 123 holon-run/holon

Publish commands

bash
1scripts/ghx.sh review publish --pr=holon-run/holon#123 --body-file=review.md --comments-file=review.json
2scripts/ghx.sh pr create --repo=holon-run/holon --title="Title" --body-file=summary.md --head=feature/x --base=main
3scripts/ghx.sh pr update --pr=holon-run/holon#123 --title="New title" --body-file=summary.md
4scripts/ghx.sh pr comment --pr=holon-run/holon#123 --body-file=summary.md
5# stdin body is also supported
6scripts/ghx.sh pr comment --pr=holon-run/holon#123 --body-file=- <<'EOF'
7Multiline body from stdin.
8EOF

Batch mode

bash
1scripts/ghx.sh batch run --batch=${GITHUB_OUTPUT_DIR}/publish-batch.json

Use batch mode when one run needs multiple publish actions. Use direct commands for single-action publish.

Contract Boundary

• Public contract for other skills:
  • Call ghx.sh commands.
  • Read ${GITHUB_CONTEXT_DIR}/manifest.json for context artifacts.
  • Read ${GITHUB_OUTPUT_DIR}/publish-results.json for publish execution results.
  • Use publish-batch.json schema when running ghx.sh batch run (defined below and in references/github-publishing.md).
• Integration guidance for third-party skills:
  • Prefer direct commands for single actions.
  • Use batch mode only when one run needs multiple publish actions.
  • Do not depend on undocumented fields or script internals outside this documented schema.

Context Output Contract

context collect writes:

• ${GITHUB_CONTEXT_DIR}/manifest.json
• Context files under ${GITHUB_CONTEXT_DIR}/github/ (for example pr.json, pr.diff, comments.json)

manifest.json is the source of truth for collected context:

json
1{
2  "schema_version": "2.0",
3  "provider": "ghx",
4  "kind": "pr|issue",
5  "ref": "owner/repo#123",
6  "success": true,
7  "artifacts": [
8    {
9      "id": "pr_metadata",
10      "path": "github/pr.json",
11      "required_for": ["review"],
12      "status": "present|missing|error",
13      "format": "json|text",
14      "description": "What this artifact contains"
15    }
16  ],
17  "notes": []
18}

Consumers must use artifacts[] instead of assuming fixed context filenames.

Publish Output Contract

Publish commands write ${GITHUB_OUTPUT_DIR}/publish-results.json with per-action status and summary totals.

Batch Input Contract (Public)

ghx.sh batch run consumes ${GITHUB_OUTPUT_DIR}/publish-batch.json (or any path passed by --batch).

json
1{
2  "version": "1.0",
3  "pr_ref": "owner/repo#123",
4  "actions": [
5    {
6      "type": "post_comment",
7      "description": "optional",
8      "params": {
9        "body": "summary.md"
10      }
11    }
12  ]
13}

Schema summary:

• Top-level required fields: pr_ref, actions
• Top-level optional field: version (default 1.0)
• Action required field: type
• Action optional fields: description, params
• params is action-specific payload; legacy inline action fields are also accepted.

Supported type values:

• create_pr
• update_pr
• post_comment
• reply_review
• post_review

Notes

• Prefer ghx for multi-step or error-prone GitHub operations.
• context collect also prints a human-readable artifact summary; this is informational only.
• For long or multi-line text, never inline shell arguments; always write to a file and pass --body-file/--comments-file.
• Command selection:
  • single action: use direct commands (review publish, pr create|update|comment)
  • multiple actions in one run: use batch run

Safety Rules (Text Payloads)

To reduce failure rate from quoting/newline/markdown escaping:

1. Never pass large markdown/JSON payloads inline on command line.
2. Always pass payloads via file arguments:
   • ghx: --body-file, --comments-file (--body-file=- is allowed to read from stdin)
   • raw gh: --body-file
3. Apply this rule to PR reviews, PR comments/description, issue comments, and issue creation.

Good:

bash
1cat > /tmp/issue-body.md <<'EOF'
2## Summary
3Detailed markdown with quotes, backticks, and newlines.
4EOF
5gh issue create --repo owner/repo --title "Bug report" --body-file /tmp/issue-body.md

Bad:

bash
1gh issue create --repo owner/repo --title "Bug report" --body "## Summary
2Detailed markdown with quotes, backticks, and newlines."