agentleFS
egregore-labsegregore-labs/egregore/.claude/skills/contribute/SKILL.md

contribute

Skill293 starsChanged 11 days agoMITView on GitHub

Contribute an improvement back to the upstream Egregore framework as a cross-fork pull request. Use for /contribute, or submitting a framework fix upstream — not saving org work (/save) or filing a bug (/issue).

  • Commits and pushes

16 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

34 rules. 0 are common, 13 are distinctive, and 21 are very specific to this project.

  • 0

    Common

    Most of the 15 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 21

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Not this: saving work to org repo → /save · filing a bug → /issue · syncing from upstream → /update

    line 14
  2. Very specific:

    Use the printed target as {upstream_repo}.

    line 35
  3. Very specific:

    If the guard refuses because upstream_url is "none", tell the user:

    line 37
  4. Very specific:

    Use the printed login as {gh_user}.

    line 52
  5. Very specific:

    If empty: "Run bash bin/github-auth.sh first — you need GitHub access to contribute." Stop.

    line 54
  6. Very specific:

    If $ARGUMENTS is non-empty (and not submit/status), use as the topic description.

    line 62
  7. Distinctive:

    If empty, ask with a structured question when available and permitted in this session.

    line 64
  8. Distinctive:

    If freeform or "Something else" → ask the user to describe the change.

    line 80
  9. Distinctive:

    Run all three steps in order:

    line 84
  10. Distinctive:

    Check whether the contribute remote exists:

    line 95
  11. Distinctive:

    If the check exits nonzero, add the remote.

    line 102
  12. Very specific:

    Use the part after / in {upstream_repo} as {repo_name}.

    line 104
  13. Very specific:

    Keep the printed value as {previous_branch} for the return in Step 13.

    line 126
  14. Distinctive:

    Check if branch exists:

    line 128
  15. Very specific:

    Use the printed value as {branch} for the branch checks below.

    line 170
  16. Very specific:

    Use the printed file list as {framework_changes}.

    line 178
  17. Distinctive:

    If changes exist on a non-contribute branch: offer to cherry-pick into a contribution branch

    line 180
  18. Very specific:

    If no changes: "No framework changes found.

    line 181
  19. Very specific:

    Use the first command's output as {diff_stat} and the second command's file list as {diff_files}.

    line 192
  20. Distinctive:

    If nothing staged: "No framework changes to submit." Stop.

    line 212
  21. Very specific:

    Commit message — per .claude/context/commit-format.md.

    line 214
  22. Very specific:

    Use {commit_message} for the commit message chosen in the preceding question, escaping embedded single quotes as '\'':

    line 226
  23. Distinctive:

    Check for org-specific content that shouldn't go upstream:

    line 234
  24. Very specific:

    Use {diff_files} from Step 7 as separate file arguments, each single-quoted.

    line 236
  25. Distinctive:

    If leaks found, ask with a structured question when available and permitted in this session.

    line 254
  26. Distinctive:

    If "Fix first" → Stop.

    line 266
  27. Very specific:

    If push fails: "Push failed.

    line 275
  28. Very specific:

    Use the printed value as {diff_stat}.

    line 285
  29. Very specific:

    Use {commit_message} from Step 8 as the title, {upstream_repo} from the guard, {gh_user} from the authenticated login, and …

    line 292
  30. Very specific:

    Use the printed URL as {pr_url} for the confirmation below.

    line 302
  31. Distinctive:

    If PR creation fails: "PR creation failed, but your branch is pushed to your fork.

    line 304
  32. Distinctive:

    If it fails, run:

    line 330
  33. Very specific:

    Use the printed branch list as {contribute_branches}.

    line 350
  34. Very specific:

    If no contribute branches: "No contributions in progress.

    line 371

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “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

Contribute an improvement back to the upstream Egregore framework.

Arguments: $ARGUMENTS

When to invoke

User says: "I want to improve this command", "submit a fix upstream", "contribute back", "send this to egregore", "contribute to the framework", "upstream PR", "fix in upstream" Not this: saving work to org repo → /save · filing a bug → /issue · syncing from upstream → /update

Argument routing

Parse $ARGUMENTS:

  • Empty → Interactive mode (ask what they want to improve)
  • submit → Submit mode (push changes + create cross-fork PR)
  • status → Show current contribution state
  • Anything else → Interactive mode with topic pre-seeded from arguments

Step 0: Gate check

Resolve the contribution target through the shared executable guard. This is mandatory for every mode, including status, and replaces any hand-written interpretation of upstream_url:

bash bin/contribute-guard.sh

Use the printed target as {upstream_repo}; quote placeholders in single quotes when you use them in a command, and write any single quote inside a value as '\''.

If the guard refuses because upstream_url is "none", tell the user:

This is the framework source repository. Use /save to push changes to its configured integration branch.

Stop.

For malformed configuration, unsupported URLs, or any other guard failure, show its error and stop. Never substitute a public target after a guard error.

Step 1: Check auth + get username

gh api user --jq '.login' 2>/dev/null

Use the printed login as {gh_user}.

If empty: "Run bash bin/github-auth.sh first — you need GitHub access to contribute." Stop.


Interactive mode (default / topic provided)

Step 2: Understand intent

If $ARGUMENTS is non-empty (and not submit/status), use as the topic description.

If empty, ask with a structured question when available and permitted in this session; otherwise ask in plain text:

header: "Contribute"
question: "What do you want to improve in the Egregore framework?"
options:
  - label: "A command"
    description: "Improve or fix a slash command"
  - label: "A script"
    description: "Improve or fix a bin/ script"
  - label: "CLAUDE.md"
    description: "Update framework behavior"
  - label: "Something else"
    description: "I'll describe what I want to change"

If freeform or "Something else" → ask the user to describe the change.

Step 3: Set up infrastructure (silent — no output to user)

Run all three steps in order:

# Revalidate immediately before the first external mutation. A target change
# or source-repository config stops the entire command block.
bash bin/contribute-guard.sh --expect '{upstream_repo}' >/dev/null || exit $?

# 3a: Fork upstream (idempotent — no-ops if fork exists)
gh repo fork '{upstream_repo}' --clone=false 2>/dev/null || true

Check whether the contribute remote exists:

# 3b: Add contribute remote (skip if exists)
git remote get-url contribute &>/dev/null

If the check exits nonzero, add the remote; if it succeeds, skip adding it:

Use the part after / in {upstream_repo} as {repo_name}.

git remote add contribute 'https://github.com/{gh_user}/{repo_name}.git' 2>/dev/null

Then fetch the remote and continue with branch setup:

git fetch contribute --quiet 2>/dev/null || true

# 3c: Create contribution branch from upstream/main
git fetch upstream main --quiet 2>/dev/null || true

Derive topic slug: lowercase the description, replace every character outside a-z0-9 with -, collapse consecutive hyphens, remove leading and trailing hyphens, then keep the first 40 characters as {topic_slug}. Use contribute/{topic_slug} as {contribute_branch}.

Save current branch for later return:

git branch --show-current

Keep the printed value as {previous_branch} for the return in Step 13.

Check if branch exists:

if git show-ref --verify --quiet 'refs/heads/{contribute_branch}' 2>/dev/null; then
  # Branch exists — ask: resume or start fresh?
fi

If new:

git checkout -b '{contribute_branch}' upstream/main --quiet

Step 4: Confirm setup

Contributing to {upstream_repo}

  Fork:   github.com/{gh_user}/{repo_name}
  Branch: {contribute_branch}
  Scope:  bin/ · .claude/commands/ · .claude/agents/ · loom/ · CLAUDE.md · skills/

Make your changes, then run /contribute submit.

Step 5: Telemetry

bash bin/telemetry.sh emit "command" '{"command":"contribute","subcommand":"start"}' 2>/dev/null &

The user now works on their changes. Claude assists normally. When ready, they run /contribute submit.


Submit mode (/contribute submit)

Step 6: Validate state

git branch --show-current

Use the printed value as {branch} for the branch checks below.

If not on a contribute/* branch: Check for framework changes vs upstream:

git diff upstream/main --name-only -- bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/ 2>/dev/null

Use the printed file list as {framework_changes}.

  • If changes exist on a non-contribute branch: offer to cherry-pick into a contribution branch
  • If no changes: "No framework changes found. Make changes first, then /contribute submit." Stop.

If on a contribute/* branch: Use {branch} as {contribute_branch} and proceed.

Step 7: Show changes for review

git diff upstream/main --stat -- bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/
git diff upstream/main --name-only -- bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/

Use the first command's output as {diff_stat} and the second command's file list as {diff_files}.

Show the diff. Also warn about out-of-scope changes:

git diff upstream/main --name-only | grep -v '^bin/' | grep -v '^\.claude/commands/' | grep -v '^\.claude/agents/' | grep -v '^loom/' | grep -v '^CLAUDE\.md$' | grep -v '^skills/' | head -5

Use the printed file list as {non_framework}.

If non-empty:

These files are outside framework scope and won't be included: {list}

Step 8: Stage framework files only

git add bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/ 2>/dev/null

If nothing staged: "No framework changes to submit." Stop.

Commit message — per .claude/context/commit-format.md; ask with a structured question when available and permitted in this session; otherwise ask in plain text:

header: "Message"
question: "Describe your contribution:"
options:
  - label: "{auto-derived from diff — e.g. 'fix(save): improve error handling'}"
    description: "Based on your changes"
  - label: "I'll write my own"
    description: "Enter a custom message"

Use {commit_message} for the commit message chosen in the preceding question, escaping embedded single quotes as '\'':

git commit -m '{commit_message}'

Step 9: Safety scan

Check for org-specific content that shouldn't go upstream:

Use {diff_files} from Step 7 as separate file arguments, each single-quoted; write any single quote inside a path as '\'':

bash bin/contribute-guard.sh scan -- {diff_files}

For a long list, write those paths, one per line, to tmp/contribute-files.txt, then run this instead:

bash bin/contribute-guard.sh scan --stdin < tmp/contribute-files.txt

The guard reads org_name, github_org, and slug from configuration and prints path:line:match rows. Exit 1 means references matched, 0 means clean (including an empty list); deleted files are skipped. On exit 2, show the error and stop.

If leaks found, ask with a structured question when available and permitted in this session; otherwise ask in plain text:

header: "Safety"
question: "Your changes contain org-specific references. Clean up before submitting?"
options:
  - label: "Fix first"
    description: "I'll clean these up"
  - label: "It's fine"
    description: "False positives or intentional"

If "Fix first" → Stop.

Step 10: Push to fork

bash bin/contribute-guard.sh --expect '{upstream_repo}' >/dev/null || exit $?
git push contribute '{contribute_branch}' -u --quiet 2>&1

If push fails: "Push failed. Your changes are saved locally. Check your network and try /contribute submit again." Stop.

Step 11: Create cross-fork PR

Refresh the diff stat for the PR body:

git diff upstream/main --stat -- bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/

Use the printed value as {diff_stat}. Write tmp/pr-body.md following .claude/context/pr-format.md, including the contribution description from the user's arguments or Step 2 answer, {diff_stat}, and the credit "Contributed via /contribute from an Egregore instance."

Revalidate {upstream_repo}, the target printed by the guard, and stop if it refuses:

bash bin/contribute-guard.sh --expect '{upstream_repo}' >/dev/null

Use {commit_message} from Step 8 as the title, {upstream_repo} from the guard, {gh_user} from the authenticated login, and {contribute_branch} from the current contribution branch:

gh pr create \
  --repo '{upstream_repo}' \
  --head '{gh_user}:{contribute_branch}' \
  --base main \
  --title '{commit_message}' \
  --body-file tmp/pr-body.md 2>&1

Use the printed URL as {pr_url} for the confirmation below.

If PR creation fails: "PR creation failed, but your branch is pushed to your fork. Create the PR manually at github.com/{gh_user}/{repo_name}." Stop.

Extract PR number from {pr_url}.

Step 12: Confirmation

┌──────────────────────────────────────────────────────────────────────┐
│  ↑ CONTRIBUTED                                  {author} · {date}   │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  {PR title}                                                          │
│  → {upstream_repo} · PR #{number}                                    │
│                                                                      │
├──────────────────────────────────────────────────────────────────────┤
│  ✓ Pushed to fork · PR created                                      │
│  {pr_url}                                                            │
└──────────────────────────────────────────────────────────────────────┘

Step 13: Return to working branch

git checkout '{previous_branch}'

If it fails, run:

git checkout develop

Step 14: Telemetry

bash bin/telemetry.sh emit "command" '{"command":"contribute","subcommand":"submit"}' 2>/dev/null &

Status mode (/contribute status)

git branch --list "contribute/*" --format="%(refname:short)"

Use the printed branch list as {contribute_branches}.

For each branch, check:

  • Diff stat vs upstream/main
  • Whether pushed to fork (git log contribute/$branch --oneline -1 2>/dev/null)
  • Whether PR exists (gh pr list --repo '{upstream_repo}' --head '{gh_user}:{branch}' --json number,state --jq '.[0]' 2>/dev/null)

Display:

↑ Contributions to {upstream_repo}

  contribute/improve-save-command
    +42/-8, 3 files · pushed · PR #17 (open)

  contribute/fix-graph-sync
    +8/-2, 1 file · local only · no PR

  /contribute submit to push the current branch.

If no contribute branches: "No contributions in progress. Run /contribute to start one."


Edge cases

ScenarioHandling
upstream_url is "none"Executable guard refuses all contribution operations and redirects to /save
upstream_url is emptyExecutable guard selects egregore-labs/egregore
Config is invalid or target changesExecutable guard fails closed before fork, push, or PR
Fork already existsgh repo fork is idempotent
contribute remote existsSkip adding
No framework changes"Make changes first, then /contribute submit"
Org-specific refs in changesSafety scan warns
Already on contribute/* branchOffer to submit or start new
PR exists for this branchShow existing PR URL, don't create duplicate
Push failsPreserve local changes, suggest retry
PR creation failsBranch is pushed, suggest manual PR

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.