name: GitHub Workflow description: "Professional GitHub workflow skill for AI agents. Covers full project lifecycle: repo setup, Git Flow branching, atomic commits, pull requests, code review, CI/CD monitoring, semantic versioning, releases, secrets management, and security rules. Includes mandatory agent behavior directives for skill installation, new projects, and returning to existing work. Features built-in work log system for task state and session continuity. Trigger on: GitHub, git, gh CLI, repo, PR, branch, merge, commit, issue, release, CI, GitHub Actions, tag, secret."

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

• Assess task scale first (see Task scale table in Agent Workflow).
• Tiny tasks: branch → commit → quick-log → PR → confirm with user → merge.
• Normal/significant tasks: Issue and work log are mandatory before branching.
• Never commit directly to main or develop.
• Never skip the pre-PR checklist on normal/significant tasks.
• 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.

Security (always)

• All operations via gh CLI. Always --repo owner/repo outside a git directory.
• 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

Read-only lookup. All write operations require explicit user confirmation — see ⚠️ markers in reference files.

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

本技能来自小葱技能站7w4.net。

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 scale

Before starting any task, assess its scale — this determines the workflow level.

When in doubt — treat as significant.

Clarification (significant tasks only)

Before creating an Issue or branching, ask until requirements are clear: - What exactly needs to change and why? - Are there affected components, APIs, or dependencies? - Any constraints — performance, backward compatibility, deadlines? - What does "done" look like?

Do not start implementation until answers are clear. For tiny/normal tasks — skip this, infer from context.

Task process

Tiny task:

1. Branch from develop          → git checkout -b fix/short-desc
2. Atomic commit                → "fix: description"
3. Append to quick-log.md       → date + one line what changed
4. ⚠️ CONFIRM WITH USER — merge via PR → gh pr merge --squash --delete-branch

Normal/significant task:

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
   If CI fails:
   - Download failed logs                  → gh run view <id> --log-failed
   - Record cause in work log              → Status.blocked or Notes
   - Fix, commit ("fix: resolve CI failure"), push
   - Wait for green before proceeding
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 follows the template below - Self-review: read your own diff one more time — check for hardcoded values, leftover debug statements, missing error handling. Only after this request human review.

PR description template:

## What
Brief description of the change.

## Why
Closes #<issue>

## Changes
- Change 1
- Change 2

## Testing
- [ ] Tests pass locally
- [ ] CI green
- [ ] Manual check done (if UI)

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

Scope creep

If during implementation something additional is discovered that wasn't in the original Issue: - Do not expand the current task - Complete current task as originally scoped - Create a new Issue for the additional work - Add a note in the current work log under Notes

Hotfix workflow

Hotfixes are emergency fixes branched from main. After merging into main, the same fix must be merged back into develop — otherwise the bug returns in the next release.

1. Branch from main                        → git checkout main && git pull
                                             git checkout -b hotfix/short-desc
2. Fix, commit                             → "fix: description"
3. Open PR → main                          → gh pr create --base main --head hotfix/...
4. Merge into main after approval          → gh pr merge --squash --delete-branch
5. ⚠️ CONFIRM WITH USER — merge into develop too → git checkout develop && git pull
                                                    git merge main
                                                    git push origin develop
6. Tag the release                         → gh release create vX.Y.Z --target main
7. Record in work log                      → what broke, what was fixed, why

Never skip step 5 — an unsynced develop will reintroduce the bug on next release.

Work Log

Every task gets a log entry. Format depends on scale.

Quick log (tiny tasks only)

One shared file per project: work/quick-log.md

## 2026-05-08
- fixed listing card spacing (components/Card.css)
- updated parser timeout (config/parser.yml)
- corrected Georgian translation (locales/ka.json)

Append one line per tiny task. No structure, no status, no decisions. Created once, never compacted.

Full log (normal / significant tasks)

Every significant task gets its own 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
• Never store secrets, tokens, or credentials in work logs
• Compact proactively — a bloated log defeats the purpose

When to read reference files

Load only what you need for the current task:

这个 Skill 质量不错，提供了从创建项目到发布版本的一整套规范流程，指令清晰、安全提示到位、分支策略明确。它能帮助 AI 代理按照专业标准完成任务，减少出错风险。不过内容偏理论导向，缺少实际例子和常见问题解答，对复杂协作场景的支持也还不够完善。