agentleFS
jahfaliabdulrahman-devjahfaliabdulrahman-dev/hermes-skills/skills/repo-front-door/SKILL.md

repo-front-door

Skill1 starsChanged 44 days agoApache-2.0View on GitHub

Turn a code repository into a credible front door for outsiders who will judge the project by its link — hackathon judges, investors, stakeholders, testers. Covers: making CI genuinely green, automating a downloadable build artifact on a rolling release, restructuring the README so the download or demo is the hero, and producing brand assets (square avatar, 1280×640 social preview card, including non-Latin/RTL text). Use this skill whenever someone outside the team will evaluate the project from its repo URL. The…

  • Deletes or force-pushes
  • Installs packages
  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 10 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill whenever someone outside the team will evaluate the project from its repo URL.

    line 21
  2. Distinctive:

    Before touching anything, gather what a stranger sees:

    line 67
  3. Distinctive:

    Read the README top-to-bottom as if you'd never seen the project.

    line 75
  4. Distinctive:

    Add the test suite to CI so green means "compiles + analyzes clean + tests pass":

    line 103
  5. Very specific:

    Keep the workflow file path stable — renaming lint.yml → ci.yml orphans the old entry in the Actions tab.

    line 127
  6. Distinctive:

    If CI genuinely can't go green in time, add an honest one-line note to the README: "CI currently fails on X.

    line 130
  7. Distinctive:

    Verify tag and HEAD agree:

    line 150
  8. Distinctive:

    Add a plain text link beside the badge as fallback.

    line 162
  9. Distinctive:

    Avoid spaces in asset filenames.

    line 169
  10. Very specific:

    Avatar: Use scripts/make_avatar.py.

    line 183
  11. Very specific:

    Keep all meaningful content ~40pt (≈53px at 1280 wide) away from edges.

    line 193
  12. Distinctive:

    Do the part you can: produce a verified file, commit it to the repo, and give the exact click path:

    line 199
  13. Distinctive:

    Every claim is checkable from outside:

    line 209

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Repo Front Door

Turn a code repository into a credible front door for outsiders who will judge the project by its link — hackathon judges, investors, stakeholders, testers. Covers: making CI genuinely green, automating a downloadable build artifact on a rolling release, restructuring the README so the download or demo is the hero, and producing brand assets (square avatar, 1280×640 social preview card, including non-Latin/RTL text).

Use this skill whenever someone outside the team will evaluate the project from its repo URL. The pieces travel together: a red ✗ reads as "the app is broken" to a non-technical evaluator no matter how well the app actually runs.

When to Use

  • "Make the repo look professional"
  • "CI is red" or "fix CI"
  • "Add a download/release" or "the APK is stale"
  • "Update the README" or "README buries the download"
  • "Create a logo/avatar/social card for the repo"
  • "Getting ready for a demo/hackathon/judge review"
  • Any one of the above — they travel together; do all relevant steps

Prerequisites

  • gh CLI authenticated (gh auth status)
  • flutter (if Flutter project), or equivalent build tool
  • Python 3 with Pillow (pip install Pillow)
  • Google Chrome or Chromium (for social card rendering)
  • Repo cloned locally with push access

How to Run

Work through the six steps in order. Each step's verification protects the next. Script paths are relative to this skill's directory — expand them with python3 ~/.hermes/skills/repo-front-door/scripts/….

Quick Reference

StepWhatKey Command
1Audit from outsidegh run list --limit 15, gh release view --json ...
2Green CIPin toolchain versions, --no-fatal-infos, verify exit code
3Download artifactCI workflow → rolling latest release, permanent URL
4README restructureDownload-first, <details> blocks, verify with gh api /markdown
5Brand assetsscripts/make_avatar.py, scripts/render_card.py
6Flag what's manualGitHub has no API for avatar/social-preview upload

Permanent download URL (never changes): https://github.com/OWNER/REPO/releases/latest/download/<asset-name>

Procedure

1. Look at the repo as an outsider first

Before touching anything, gather what a stranger sees:

gh run list --limit 15
gh release view --json tagName,publishedAt,assets
gh repo view --json owner,description,homepageUrl

Read the README top-to-bottom as if you'd never seen the project. Where is the download? How many scrolls?

Report what you find plainly, including how long a problem has existed.

2. Make CI green — and make green mean something

Trap 1 — toolchain version drift. CI pinned to an older SDK produces errors that exist only in CI:

flutter --version                        # local
grep -rn "version" .github/workflows/   # CI

Pin CI to the version actually used to build. A CI testing a different toolchain than you ship is testing fiction.

Trap 2 — linters exit non-zero on advisory findings. flutter analyze exits 1 on info-level hints. Verify with:

flutter analyze --no-fatal-infos; echo "exit: $?"

Make advisory findings non-blocking, but fix real warnings rather than muting them.

Add the test suite to CI so green means "compiles + analyzes clean + tests pass":

name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  analyze-and-test:
    name: Analyze & Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.44.6'
          channel: 'stable'
      - run: flutter pub get
      - run: flutter analyze --no-fatal-infos
      - run: flutter test

Keep the workflow file path stable — renaming lint.yml → ci.yml orphans the old entry in the Actions tab.

If CI genuinely can't go green in time, add an honest one-line note to the README: "CI currently fails on X; the app builds and runs, see below."

3. Guarantee a working download

Automate the build so the artifact can never drift from the code. See references/ci-and-releases.md for the complete workflow.

The permanent URL:

https://github.com/OWNER/REPO/releases/latest/download/<asset-name>

The tag gotcha: gh release upload latest <file> --clobber swaps the asset but does NOT move the git tag. Fix: git tag -f latest "$GITHUB_SHA" && git push -f origin latest as part of the build.

First run needs the release created: gh release create latest --title "Latest build" --notes "Automatically built." || true

Verify tag and HEAD agree:

gh api repos/OWNER/REPO/git/refs/tags/latest --jq '.object.sha'
git rev-parse HEAD

4. Make the README download-first

Structure: logo → name → one-line pitch → big download button → everything else. The download should be visible without scrolling.

  • A shields.io badge wrapped in <a> reads as a real button.
  • Add a plain text link beside the badge as fallback.
  • Push deep docs into <details> blocks.
  • For chat/conversational products, a sample conversation conveys the idea better than screenshots — and leaks nothing.

Never publish screenshots from a real logged-in session.

Avoid spaces in asset filenames. Verify the render before pushing:

gh api --method POST /markdown -f mode=gfm -f text="$(cat README.md)" > /tmp/r.html

5. Brand assets

Two different things, often confused:

AssetScopeSize
Account avatarEvery repo + profileSquare, 500px+
Social previewOne repo1280×640

Avatar: Use scripts/make_avatar.py. Derives crop from pixels, pads, and verifies nothing clips under the circular crop platforms apply.

Social card: Compose in assets/social-card-template.html, render with scripts/render_card.py. Why a browser? Pillow cannot shape complex scripts (Arabic, Persian, Urdu, Hindi, Thai) unless built with raqm. Check:

python3 -c "from PIL import features; print(features.check('raqm'))"

Keep all meaningful content ~40pt (≈53px at 1280 wide) away from edges. render_card.py measures real margins and fails when content intrudes.

6. What you cannot automate

GitHub has no API for uploading an account avatar or a repo social preview. Do the part you can: produce a verified file, commit it to the repo, and give the exact click path:

  • Avatar → https://github.com/settings/profile → click avatar → Upload a photo…
  • Social preview → repo Settings → General → Social preview → Edit → Upload an image…

Flag the scope surprise: the avatar changes every repo on that account.

Verification

Every claim is checkable from outside:

# Download actually serves the artifact
curl -sIL "https://github.com/OWNER/REPO/releases/latest/download/<asset>" \
  | grep -iE "^HTTP/2 200|content-type|content-length"

# Logo actually resolves from the README's path
curl -s -o /dev/null -w "%{http_code}\n" \
  "https://raw.githubusercontent.com/OWNER/REPO/main/<path>"

# CI actually passes now
gh run watch <run-id> --exit-status

Watch a build through to completion rather than pushing and assuming.

Pitfalls

  • Tag drift: gh release upload latest --clobber updates the asset but not the tag. Always move the tag in the build workflow.
  • Workflow rename: Renaming a workflow file orphans the old entry in the Actions tab. Edit the file in place instead.
  • Pillow + non-Latin text: Pillow renders Arabic/Persian/etc. disconnected and backward without raqm. Use a browser for text rendering.
  • Avatar scope: Changing the account avatar changes it for every repo and the profile page — alert the user before they upload.
  • Screenshots from live session: A real device mid-demo exposes the owner's name, email, and data. Use guest state or skip screenshots.
  • Spaces in asset filenames: logo.jpeg forces %20 in references. Use hyphenated names.
  • In-repo README images break regionally when raw.githubusercontent.com is down. Relative-path images are served through raw.githubusercontent.com, so a Fastly/edge incident there breaks every in-repo README image for viewers in that region — while the page HTML still loads, making it look repo-specific when it isn't (verify: curl any raw URL for a big public repo; if it fails too, it's the host, not the repo). A cloud-browser check from another region masks the problem — always test from the audience's network. Resilient fix: point featured images at a public CDN — https://cdn.jsdelivr.net/gh/OWNER/REPO@REF/<path> — GitHub proxies external images through camo (a different backend); then re-verify from the audience side by extracting the camo URL from the rendered README HTML and curling it.

Reference files

  • references/ci-and-releases.md — complete CI + build-and-publish workflows, secrets, tag mechanics
  • references/brand-assets.md — avatar and social card specs, complex-script rendering, safe zones

Scripts

  • scripts/make_avatar.py — logo → square avatar, with circular-crop preview
  • scripts/render_card.py — HTML → exact-size PNG via headless Chrome, with safe-zone measurement
  • assets/social-card-template.html — starting point for a social card (RTL-ready)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.