github-contribution-intel

name

github-contribution-intel

description

Gathers contribution-oriented documents from a public GitHub repository into a local artifact folder. Use when the user provides a GitHub URL and wants onboarding or contribution context (README, contributing guidelines in Markdown or reStructuredText, bounded follow-through of in-repo contributing links, code of conduct, license, security policy, issue/PR templates), or before opening a first PR or fork on an unfamiliar public repo.

GitHub contribution intel

Goal

Given a public GitHub repository URL, collect the files maintainers typically expect contributors to read, write them under agent-artifacts/github-contribution-intel/<run-id>/, and emit manifest.json, INTEL.md, and COMBINED.md so the agent (or human) can scan one place.

When not to use

• Private repositories, GitHub Enterprise, or hosts other than github.com (needs different auth or URLs).
• Mirroring entire docs/ trees or full source—stay with governance and contributor-facing files only.

Output layout (repository root)

agent-artifacts/github-contribution-intel/{owner}-{repo}-{YYYYMMDDTHHMMSSZ}/
  manifest.json
  INTEL.md
  COMBINED.md
  files/                 # individual downloads mirror repo paths (e.g. files/README.md)
    README.md
    CONTRIBUTING.rst
    ...

Use UTC in the run id suffix. If the parent folders do not exist, create them.

Input: normalize the GitHub URL

Accept common forms and extract owner and repo (case-sensitive as on GitHub):

• https://github.com/org/repo
• http://github.com/org/repo/
• https://www.github.com/org/repo.git
• github.com/org/repo (prefix https:// mentally)

Strip query strings. Ignore fragments for clone/fetch purposes. repo must not contain further slashes (not a subdirectory URL).

If parsing fails, stop and report the error; do not guess owner/repo.

Resolve default branch

1. Preferred: GET https://api.github.com/repos/{owner}/{repo} with User-Agent, Accept: application/vnd.github+json, optional Authorization: Bearer (see authentication below), and X-GitHub-Api-Version. Read default_branch.
2. Fallback: if the API fails (network, 403 rate limit, etc.), assume main, then master for raw URLs: use the first branch for which README.md or README.rst returns HTTP 200, or if neither works, record the failure in manifest.json and still attempt other paths with main then master separately.

Authentication (same order as the bundled script): GITHUB_TOKEN or GH_TOKEN, else gh auth token if the GitHub CLI is installed and logged in; otherwise unauthenticated API calls. INTEL.md summarizes which case applied and rate-limit expectations.

Files to collect (checklist)

Save each found file under files/ using the repository-relative path as the relative path (create subdirs as needed). Record every attempted path in manifest.json with HTTP status or error, and the local path when saved.

High priority (try every path listed; many projects use .rst instead of .md)

Role	Paths tried (in order)
README	README.md, README.rst
Contributing	CONTRIBUTING.md, CONTRIBUTING.rst, docs/contributing.md, docs/contributing.rst
Code of conduct	CODE_OF_CONDUCT.md, CODE_OF_CONDUCT.rst
License	LICENSE, LICENSE.md, LICENSE.txt, LICENSE.rst, COPYING (first match wins; still log others as skipped or not found)
Security	SECURITY.md, SECURITY.rst, .github/SECURITY.md
PR template	.github/PULL_REQUEST_TEMPLATE.md, .github/pull_request_template.md
Issue templates	.github/ISSUE_TEMPLATE/* — list directory via Contents API; fetch each file (.md, .markdown, .rst, .yaml, .yml, .txt)

Lower priority (fetch if present)

• GOVERNANCE.md, GOVERNANCE.rst, MAINTAINERS, SUPPORT.md, SUPPORT.rst
• CHANGELOG.md, CHANGELOG.rst, CHANGES.rst, DEVELOPMENT.md, DEVELOPMENT.rst, BUILD.md, BUILD.rst

Do not recurse into all of docs/ unless the user explicitly asks.

Contributing link expansion (stub → real guide)

Some repos keep a short CONTRIBUTING.* / docs/contributing.* that only links to the real guide (for example Apache Airflow’s CONTRIBUTING.rst → contributing-docs/README.rst). After those seed files are fetched, the bundled script performs a bounded BFS:

• Seeds: CONTRIBUTING.md, CONTRIBUTING.rst, docs/contributing.md, docs/contributing.rst (when present in the run).
• Link detection: Markdown []() targets and RST inline `text <path>`__ / `text <path>`_ where path is repo-relative (not http(s):).
• Targets: only paths ending in .md, .markdown, .rst, or .txt; relative URLs are resolved from the current file’s directory; paths that walk above the repo root (.. escape) are skipped.
• Limits (defaults in fetch_github_intel.py): max 2 edges from a seed, max 48 extra files. This is not a full docs/ mirror—only pages reachable via those links within the caps.
• manifest.json: each extra file includes "note": "followed from <repo-path>".
• INTEL.md: Contributing link expansion lists how many files were added and shows paths (truncated if long).
• COMBINED.md: expanded files appear after the fixed high-priority list and before the license section, in BFS order.

Fetch order (implementation preference)

1. Raw GitHub: https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path} for known file paths.
2. Contents API: GET /repos/{owner}/{repo}/contents/{path} for listing .github/ISSUE_TEMPLATE (and validating paths). Use the same API headers as the default-branch request (including auth when available).
3. Shallow git clone: git clone --depth 1 https://github.com/{owner}/{repo}.git into a temporary directory under the run folder, then copy only the paths above—use if API or raw access is incomplete from the environment.
4. HTML pages: last resort for discovery only; prefer raw/API.

Deliverables

manifest.json

JSON object including at least:

• owner, repo, default_branch (resolved or assumed)
• html_url: https://github.com/{owner}/{repo}
• created_at_utc: ISO8601 when the run finished
• entries: array of { "path", "url", "http_status" | null, "saved_as" | null, "note" } for every attempt (including issue template files and contributing link expansions).

INTEL.md

Short summary: repo link, branch used, grouped bullet lists of found vs missing high-priority roles (README, contributing guide, code of conduct, license, security, PR template), contributing link expansion (extra paths fetched from seed links, if any), a list of issue template files collected (if any), path to files/, and any caveats (rate limit, fallbacks used).

COMBINED.md

Concatenate the successful text fetches in a stable order: high-priority paths in the script’s fixed order (every file that was found), then contributing expansion paths in BFS order (if any), then the license file, then lower-priority paths in their fixed order, then issue templates (alphabetical by path). Each section starts with a markdown heading that includes the repo-relative path.

Automation

Prefer running the bundled script (stdlib only, no extra packages):

python skills/github-contribution-intel/scripts/fetch_github_intel.py "https://github.com/OWNER/REPO"

Run from the project root. The script creates the run directory and writes manifest.json, INTEL.md, COMBINED.md, and files/.

If the script cannot be run, follow the same steps manually and match the output shape as closely as possible.