GitHub Skill

Agent Directives

These are mandatory behavioral rules. Follow them in every situation involving code, projects, or tasks.

On skill installation

When this skill is first loaded, introduce it to the user:

• Explain that all project work will now follow a professional GitHub workflow
• Mention: branching strategy, work logs, CI checks, semantic versioning, security rules
• Ask: "Do you have an existing project, or are we starting a new one?"

On new project

If this is the user's first project ever:

• Check gh auth status — if not authenticated, run gh auth login --web before anything else
• Offer to create a new repo: name, visibility (public/private), license, .gitignore
• Set up branch protection on main and develop right away
• Clone into ~/workspace/projects/<repo-name>/
• Create initial develop branch
• Confirm setup is complete before starting any work

If the user already has projects:

• Ask which repo they want to work on, or detect from context
• Clone into ~/workspace/projects/<repo-name>/ if not already there
• Verify branch protection is in place — if not, offer to set it up
• Proceed directly to task workflow

On continuing existing work

When the user returns to an already-cloned project — run the Session start checklist (see Agent Workflow below) before making any changes.

On every task

• Every task must have an Issue. If there is none — create one before branching.
• Every task must have a work log file in work/. Create it immediately after the Issue.
• Never commit directly to main or develop.
• Never skip the pre-PR checklist.
• Never expose tokens, secrets, or credentials in any command or output.
• If something is irreversible (delete, merge, release, force push) — always confirm with the user first.

On using this skill

• This file (SKILL.md) is always in context — use it for workflow, branching, work log rules.
• Reference files are loaded on demand only — read them when the task requires it, not upfront.
• Work log is not optional — it is part of every task from start to finish.
• When in doubt about a GitHub operation — check the relevant reference file before acting.

gh CLI for all operations. Always --repo owner/repo outside a git directory.

Security (always)

• Auth: gh auth login --web or GITHUB_TOKEN env var
• Secrets: gh secret set NAME --repo owner/repo (interactive, never --body)
• Never print/log tokens. gh auth status to verify.

Quick Reference

Branching Model

main       ← production, protected
develop    ← integration
feature/*  ← from develop
fix/*      ← from develop (reference issue: fix/123-desc)
hotfix/*   ← from main (emergency)
release/*  ← from develop (prep)
chore/*    ← from develop (deps, tooling, CI — no product change)

Commit convention: feat: description (#42) / fix: description (#42) PR merge: --squash for features, --merge for releases. Semver: MAJOR.MINOR.PATCH — breaking/feature/fix.

Agent Workflow

Workspace layout

Always clone into ~/workspace/projects/<repo-name>/. Never work in /tmp — it doesn't persist between sessions.

mkdir -p ~/workspace/projects
gh repo clone owner/repo ~/workspace/projects/repo-name
cd ~/workspace/projects/repo-name

Session start (every time)

gh auth status                   # 1. verify auth
git checkout develop && git pull # 2. sync before any work
git branch                       # 3. confirm you're on the right branch
# 4. open work/<issue>-<desc>.md and read Status.next

Task process

1. Create or find the Issue                → gh issue create / gh issue list
2. Create work log file                    → work/<issue>-<desc>.md (see Work Log section below)
3. Branch from develop                     → git checkout -b feature/42-short-desc
4. Make small atomic commits               → one change per commit
5. Commit message references Issue         → "feat: description (#42)"
6. Open draft PR after first commit        → gh pr create --draft (signals work in progress early)
7. Monitor CI                              → gh run watch
8. Pre-PR checklist (see below)
9. Mark ready + request review             → gh pr ready / gh pr review
10. Merge after approval                   → gh pr merge --squash --delete-branch
11. Close Issue + compact work log         → gh issue close 42

Pre-PR checklist

Before marking PR ready:

• Run tests locally
• git diff origin/develop — no debug code, credentials, or temp files
• CI is green (gh pr checks <n>)
• PR description has "Closes #<issue>"

Between sessions

If a task is unfinished at end of session:

git stash push -m "wip: description of what's in progress"

Update Status and next in the work log, then stop. On next session: read next, then git stash pop.

Merge conflicts

When a conflict occurs during merge or rebase:

git status                         # see conflicted files
# Open each file — resolve manually, keep correct code
git add <resolved-file>
git rebase --continue              # or git merge --continue

# If too complex — abort and ask the user
git rebase --abort
git merge --abort

Rules:

• Never blindly accept --ours or --theirs without understanding the diff
• If unsure which change is correct — stop and ask the user
• After resolving, re-run tests before pushing

Work Log

Every task gets a log file. It is the agent's memory — orientation, decisions, state.

Setup

mkdir -p work
# Add to .gitignore once per project
echo "work/" >> .gitignore

File: work/<issue-number>-<short-desc>.md

Structure

# Task: <title> (#<issue>)
Goal: <one sentence — what "done" means>

## Status
current: <what agent is doing right now>
next: <planned next action>
blocked: <blocker or —>

## Done
- [x] Created branch feature/42-user-auth
- [x] Added JWT middleware (src/auth.js)
- [ ] PR review pending

## Decisions
- Used HS256 — no key infrastructure in this project
- Skipped refresh token — out of scope per Issue comment

## Notes
- src/auth.js:84 — edge case when token is exactly expired, needs attention
- AUTH_SECRET env var must be added to secrets before deploy

When to write

Compacting

Compact when file exceeds ~80 lines or when task is complete.

• Done — keep unchecked + last 3 completed, drop the rest
• Decisions — keep all, never delete
• Notes — drop resolved, keep open
• Status — rewrite fresh

Rules

• Always update next before ending a session — it is the re-entry point
• Never delete Decisions — they prevent re-debating solved problems
• Compact proactively — a bloated log defeats the purpose

When to read reference files

Load only what you need for the current task: