Track Repository Progress

Summary

Track Repository Progress is an installable agent skill for ChatGPT, Codex and other Agent Skills-compatible tools. It inspects only the GitHub repositories a user explicitly authorizes and turns them into consistent, trackable progress reports, updating a Google Sheet only when the user asks.

My role

I designed and wrote the skill package: its instructions and command set, the evidence-based status model, the report and spreadsheet schema, the agent interface metadata and the bilingual installation and usage guide.

Problem

Following several projects means repeatedly opening each repository, reading recent commits and documents, and judging how far along it really is. Done ad hoc, by hand or by an AI agent without rules, the answers drift: roadmap promises get reported as finished work, activity gets mistaken for progress, and an agent with broad account access may look at repositories it was never asked to review.

Users and use case

The skill is for developers and small teams who track several GitHub repositories and already work with an AI agent such as ChatGPT, Codex, Claude Code, Cursor or GitHub Copilot in VS Code. It is used to review, compare or record repository progress, including keeping a shared Google Sheet up to date.

Constraints

The skill is a set of instructions, not a hosted service. It runs inside whichever agent installs it and relies on that agent's own GitHub and Google Drive connections; installing it grants no access by itself, and private repositories stay limited by the connected account's permissions. It also has to work across agents that discover skills from different directories.

Solution

Four commands cover the workflow: report generates a progress report without writing anything, compare checks current evidence against a previous report or record, preview-sheet shows the exact spreadsheet changes, and update-sheet writes them. The first report names the repository allowlist; later commands in the same conversation reuse it.

Each report leads with a portfolio summary: the reporting date and timezone, the repositories reviewed, how many are active, quiet, stale, paused or closed, the strongest recent progress, the most important shared risk and a recommended focus. One record per repository follows, with its start date and basis, stage, activity, a conservative progress estimate, last activity, completed work, next step, risks, confidence, evidence links and update time.

For Google Sheets, the skill first inspects tab names, headers and existing repository identifiers. It matches rows by the exact owner and repository name, preserves unknown columns and formulas, updates only the requested rows and fields, adds rows only for allowlisted repositories, and reports the exact tab and range it changed.

Architecture and workflow

The package follows the open Agent Skills layout: a SKILL.md entry point with the commands, workflow and evidence rules, a status model and an output schema as reference documents, and interface metadata for ChatGPT.

An inspection resolves the allowlist first and asks for one if it is missing or ambiguous. The agent then reads the minimum evidence from each allowed repository: default branch and creation metadata, README, roadmap, design and status documents, recent commits and meaningful branches or pull requests, and releases, deployments, tests or issues only when relevant. Repository text is treated as data, never as instructions. Dates, stage, activity and confidence come from the status model, and important conclusions cite direct evidence with inference clearly labelled.

Key decisions

The allowlist is the authorization boundary: the skill never discovers extra repositories just because the connected account can see them. It is read-only by default, previews spreadsheet changes before writing, and never creates issues, edits repositories or changes permissions as part of progress tracking.

Evidence outranks plans. A roadmap checkbox, branch name or README promise is not treated as completed work, commit count is never used as a progress percentage, and technical completion is kept separate from market validation. A progress estimate is given only when the project has a stated scope; otherwise the record says it is not estimable, and an empty or inaccessible repository is reported as having insufficient evidence.

Testing and delivery

The skill is distributed as source on GitHub. In ChatGPT, the skill folder is zipped with SKILL.md at the top level and uploaded on the Skills page, then GitHub and, for spreadsheet updates, Google Drive are connected. For Codex, Claude Code, Cursor, GitHub Copilot in VS Code and other compatible agents, the folder is copied into the agent's project or user skills directory and invoked by name or slash command. Agents without skill support can load SKILL.md and its references as system instructions, without automatic triggering or connector access.

The repository does not include an automated test suite or evaluation set. Behaviour is specified through written rules, a fixed output schema and explicit evidence and safety constraints rather than verified by automated checks.

Current limitations

Progress is an evidence-based estimate, not a measure of engineering hours, and commit volume shows activity rather than quality or commercial readiness. Results depend on the host agent following the written rules and on the access its GitHub and Google Drive connections provide. Without an evaluation suite, changes to the rules cannot yet be checked automatically, and the fallback for agents without skill support loses automatic triggering.

Lessons and next steps

For an AI workflow, the useful product is the boundary as much as the output: an explicit allowlist, read-only defaults and a clear line between evidence and inference make the report something a person can trust and check. The clearest next step is a repeatable set of evaluation cases built on sample repositories, so rule changes can be verified across agents rather than judged by reading the output.