gitlab-workflow

AI Agent Skills for managing the complete GitLab workflow — plan milestones, track issues, commit with traceability, open merge requests, and manage story/epic hierarchies via the glab CLI.

Quickstart

Install for your agent: Claude Code · Cursor · Codex

How it works

When you ask your agent to open an issue, create a milestone, commit staged changes, draft a merge request, or manage a story hierarchy, gitlab-workflow activates automatically. It reads the codebase, pulls relevant context from git and GitLab, and builds a complete artifact draft — title, labels, milestone, code snippets with exact path/file.ext:line citations, and Mermaid diagrams where the policy calls for them.

Before running a single glab command, the agent shows you the full draft and waits for explicit approval. If you request changes, it applies them and re-presents. Only when you confirm does it publish to GitLab.

Artifacts are language-agnostic: section headings and prose follow your active language at runtime. No language is hardcoded.

Workflow overview

The five skills cover the full GitLab development lifecycle from sprint planning to merge:

sequenceDiagram
    actor Dev as Developer
    participant A as AI Agent
    participant GL as GitLab

    Dev->>A: "Plan sprint 3: auth migration"
    A->>GL: glab milestone create
    GL-->>A: milestone/3
    A-->>Dev: ✓ Milestone #3 created

    Dev->>A: "Create a story for the auth migration"
    A->>GL: glab label list + milestone list
    A-->>Dev: Draft story — approve?
    Dev->>A: yes
    A->>GL: glab issue create (kind::story)
    GL-->>A: issue #10
    A-->>Dev: ✓ Story #10 created

    Dev->>A: "Add issues #11 #12 as children of #10"
    A->>GL: glab issue view #11 / #12
    A->>GL: glab issue link #11 --target-id #10
    A->>GL: glab issue link #12 --target-id #10
    A-->>Dev: Updated children table — approve?
    Dev->>A: yes
    A->>GL: glab issue update #10
    A-->>Dev: ✓ Children linked

    Dev->>A: "Start working on issue #11"
    A->>GL: glab issue edit #11 (workflow::in dev)
    A-->>Dev: ✓ Branch fix/11-oauth-handler created

    Note over Dev,GL: ... development ...

    Dev->>A: "Commit staged changes"
    A-->>Dev: fix(#11): handle OAuth token expiry — approve?
    Dev->>A: yes
    A->>A: git commit
    A-->>Dev: ✓ Committed abc1234

    Dev->>A: "Create MR for this branch and close #11"
    A->>GL: glab label list + diff analysis
    A-->>Dev: Draft MR — approve?
    Dev->>A: yes
    A->>GL: glab mr create
    GL-->>A: MR !5
    A-->>Dev: ✓ MR !5 created

    Dev->>A: "Link MR !5 to story #10"
    A->>GL: glab mr view !5 + commits
    A-->>Dev: Updated parent issue — approve?
    Dev->>A: yes
    A->>GL: glab issue update #10
    A-->>Dev: ✓ Story #10 updated with MR reference

    Dev->>A: "Sync story #10 children status"
    A->>GL: glab issue view #11 + #12
    A-->>Dev: Before/after table diff — approve?
    Dev->>A: yes
    A->>GL: glab issue update #10
    A-->>Dev: ✓ Children table synced

Skills

`gitlab-plan` — Milestone author

Trigger phrases: "Create a milestone", "Plan sprint 5", "Start release v2.1", "Close the current milestone", "Extend the due date of sprint 3"

What it produces:

Milestone with title, start date, due date, and a goal description
Candidate issues from the current backlog suggested for assignment
Consistent naming with project versioning (v1.2.0, Sprint 5, 2026-Q2)

Modes:

Mode	Command	When to use
Create	`glab milestone create`	New sprint or release
Update	`glab milestone edit`	Extend deadline, rename, update description
Close / Reopen	`glab milestone close / reopen`	End of sprint; re-open if work resumes

Context extracted silently: recent git log, active branches, existing milestones, open issues.

Boundary: not for issue creation (→ gitlab-track) or merge requests (→ gitlab-review).

`gitlab-track` — Issue author

Trigger phrases: "Open a bug for…", "Track technical debt in…", "Propose a feature to…", "Create a documentation issue for…", "Start working on #N", "Move #N to in review"

Issue types:

Type	Default label	Template
`bug`	`type::bug`	Steps to reproduce, root cause, affected area, code snippet
`feature`	`type::feature`	Problem, proposal, MVC, acceptance criteria, open questions
`technical-debt`	`type::technical-debt`	Current state, impact, proposed fix, effort estimate
`documentation`	`type::documentation`	Scope, audience, sections to add or update

What it produces:

Issue with title (≥ 5 meaningful words), scoped labels, optional milestone
Fenced code snippets of 5–20 lines with exact path/file.ext line N citations
Mermaid diagrams for flows, component relationships, and state machines where relevant
workflow::ready as initial lifecycle label

Lifecycle transitions (Transition mode):

workflow::ready → workflow::in dev → workflow::in review → workflow::done → closed

On transition to workflow::in dev, the skill offers to create a branch following the <type>/<issue-id>-<short-title> convention (e.g. fix/87-nil-pointer-handler).

Context extracted silently: git log, git diff HEAD, git blame (bug/tech-debt), codebase exploration with Read, Grep, Glob.

Boundary: not for merge requests (→ gitlab-review) or milestones (→ gitlab-plan).

`gitlab-commit` — Commit author

Trigger phrases: "Commit staged changes", "Save progress", "Finalize this", or implicitly when the agent signals that implementation work is complete.

What it produces:

Conventional Commit message (v1.0.0 spec) with the GitLab issue ID as scope, extracted from the branch name:

fix(#87): handle nil pointer in user handler

Closes #87

Branch-to-type mapping:

Branch prefix	Commit type	Footer
`fix/`, `hotfix/`, `bugfix/`	`fix`	`Closes #N`
`feature/`	`feat`	`Closes #N`
`refactor/`	`refactor`	`Related to #N`
`docs/`	`docs`	`Related to #N`
`chore/`	`chore`	(none)

The scope is always #N (issue ID), never a directory name.

Guard: does not auto-stage files. Stops if nothing is staged.

Context extracted silently: git branch --show-current, git diff --staged --stat, git log --oneline -5.

Boundary: does not push. Does not create MRs (→ gitlab-review).

`gitlab-review` — Merge request author

Trigger phrases: "Create MR for this branch", "Write the MR description", "Draft merge request and close #42", "Open a WIP MR"

What it produces:

MR title with conventional commit prefix matching branch intent
Description with change summary, code snippets (5–20 lines, path/file.ext line N), reviewer notes (omitted if no non-obvious design decisions), and closing references
Closes #N / Related to #N aggregated from commit history — never guessed
Labels and milestone inferred from associated issues

Modes:

Mode	Flag	When to use
Ready	(none)	Branch is ready to merge
Draft	`--draft`	Work in progress, early feedback needed

Context extracted silently: git log <base>...HEAD, git diff <base>...HEAD, commit message bodies parsed for Closes #N / Related to #N patterns.

Post-creation: offers to move the linked issue to workflow::in review.

Boundary: not for issue creation (→ gitlab-track) or milestones (→ gitlab-plan).

`gitlab-story` — Story and epic hierarchy author (v1.1.0)

Trigger phrases: "Create a story for…", "Create an epic for…", "Add issue #12 to story #10", "Sync the children of story #10", "Link MR !5 to story #10"

What it produces:

Parent issue with kind::story or kind::epic label, a structured description, and a live markdown children table tracking all child issues:

| # | Title | Type | Status | MR |
|---|-------|------|--------|----|
| [#11](…) | Handle OAuth token expiry | `type::feature` | `workflow::in dev` | !5 |
| [#12](…) | Add refresh token rotation | `type::feature` | `workflow::ready` | — |

Child issues are linked to the parent via glab issue link --link-type relates_to.

Modes:

Mode	When to use
Create	Start a new epic or story with an empty children table
Add-Child	Link existing issues or create new minimal issues as children
Sync	Refresh all child statuses from GitLab into the parent description table
Link-MR	Attach an MR reference to the parent and update the MR column for referenced children

Simulates Scrum hierarchy on GitLab Free:

epic (kind::epic)
└── story (kind::story)
    ├── feature issue #11  (type::feature, workflow::in dev, MR !5)
    └── feature issue #12  (type::feature, workflow::ready)

No GitLab Premium required. Hierarchy state is persisted entirely in the parent issue description.

Boundary: not for leaf issues (→ gitlab-track) or milestones (→ gitlab-plan).

Installation

Claude Code

claude plugins install @codeskine/gitlab-workflow

Cursor

rm -rf /tmp/gitlab-workflow
git clone https://github.com/codeskine/gitlab-workflow.git /tmp/gitlab-workflow
mkdir -p .cursor/skills && cp -r /tmp/gitlab-workflow/skills/. .cursor/skills/

Codex

rm -rf /tmp/gitlab-workflow
git clone https://github.com/codeskine/gitlab-workflow.git /tmp/gitlab-workflow
mkdir -p .codex/skills && cp -r /tmp/gitlab-workflow/skills/. .codex/skills/

Usage examples

Sprint planning

"Create a milestone for the Q3 auth migration release, due 2026-09-30"
"Create a story for the OAuth2 integration — target milestone Sprint 3"
"Add issues #11, #12, and #13 as children of story #10"

Issue tracking

"Open a bug for the double-close on the done channel in pkg/worker/main.go"
"Track technical debt for repeated allocations in AzureClientController"
"Propose a feature to improve CI onboarding for new contributors"
"Create a documentation issue for the feature flag introduced in !224136"
"Start working on issue #11"

Development cycle

"Commit the staged changes"
"Commit — this fixes the token expiry bug"
"Write the MR description for this branch and close issue #42"
"Open a Draft MR for early feedback on the auth refactor"

Story management

"Sync the children table of story #10"
"Link MR !5 to story #10"
"Show me the status of the auth migration epic"

Full sprint cycle (sequence)

1. "Create milestone Sprint 3"                          → gitlab-plan
2. "Create a story for OAuth migration"                 → gitlab-story (Create)
3. "Add issues #11 #12 as children of story #10"       → gitlab-story (Add-Child)
4. "Start working on issue #11"                         → gitlab-track (Transition)
5. "Commit staged changes"                              → gitlab-commit
6. "Create MR for this branch and close #11"           → gitlab-review
7. "Link MR !5 to story #10"                           → gitlab-story (Link-MR)
8. "Sync story #10 children status"                    → gitlab-story (Sync)

Artifact style

Conventions applied across all skills:

Dense, affirmative technical prose — no emoji, no filler preambles
path/file.ext line N citation for every code snippet
Fenced code blocks of 5–20 lines per significant point
- [ ] checklists for activities and requirements
Mermaid diagrams for flows and component relationships where relevant
All glab commands use --description "$(cat /tmp/file.md)" — never --body

Section headings and prose follow your active language at runtime.

Requirements

Dependency	Version	Install
`glab`	≥ 1.40	`brew install glab`
`glab` authenticated	—	`glab auth login`
Agent with skills support	—	Claude Code, Cursor, or Codex
Git	≥ 2.30	pre-installed on most systems
GitLab tier	Free or higher	All features work on GitLab Free

Note: gitlab-story does not require GitLab Premium. It simulates epic/story hierarchy using labels and description tables on GitLab Free.

References

Resource	URL
`glab` CLI documentation	https://gitlab.com/gitlab-org/cli/-/blob/main/docs/source/index.md
GitLab REST API	https://docs.gitlab.com/ee/api/rest/
GitLab Issue Links API	https://docs.gitlab.com/ee/api/issue_links.html
Conventional Commits v1.0.0	https://www.conventionalcommits.org/en/v1.0.0/
Mermaid diagram syntax	https://mermaid.js.org/syntax/sequenceDiagram.html
Agent Skills specification	https://agentskills.io/specification.md
`@codeskine/gitlab-workflow` on npm	https://www.npmjs.com/package/@codeskine/gitlab-workflow

Contributing

Adding a new sub-skill

Create skills/<name>/SKILL.md with all required frontmatter fields (see CLAUDE.md)
Add assets/<type>.md templates for each artifact type the skill handles
Optionally add references/ for detailed documentation
Add "<name>" to the skills array in .claude-plugin/plugin.json, .cursor-plugin/plugin.json, and .codex-plugin/plugin.json
Run the description quality check: contains GitLab, has "Use when" trigger clause, no over-triggering patterns

Modifying an existing skill

After changes:

Increment metadata.version in the changed SKILL.md
Bump version in package.json
Format: npx prettier --write "**/*.md"
Measure token count: npx tiktoken-cli skills/<name>/SKILL.md (target: < 2500)

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.cursor-plugin		.cursor-plugin
.github/workflows		.github/workflows
assets/images		assets/images
evals		evals
skills		skills
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
package.json		package.json
skills.sh.json		skills.sh.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

gitlab-workflow

Quickstart

How it works

Workflow overview

Skills

`gitlab-plan` — Milestone author

`gitlab-track` — Issue author

`gitlab-commit` — Commit author

`gitlab-review` — Merge request author

`gitlab-story` — Story and epic hierarchy author (v1.1.0)

Installation

Claude Code

Cursor

Codex

Usage examples

Sprint planning

Issue tracking

Development cycle

Story management

Full sprint cycle (sequence)

Artifact style

Requirements

References

Contributing

Adding a new sub-skill

Modifying an existing skill

License

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

gitlab-workflow

Quickstart

How it works

Workflow overview

Skills

gitlab-plan — Milestone author

gitlab-track — Issue author

gitlab-commit — Commit author

gitlab-review — Merge request author

gitlab-story — Story and epic hierarchy author (v1.1.0)

Installation

Claude Code

Cursor

Codex

Usage examples

Sprint planning

Issue tracking

Development cycle

Story management

Full sprint cycle (sequence)

Artifact style

Requirements

References

Contributing

Adding a new sub-skill

Modifying an existing skill

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`gitlab-plan` — Milestone author

`gitlab-track` — Issue author

`gitlab-commit` — Commit author

`gitlab-review` — Merge request author

`gitlab-story` — Story and epic hierarchy author (v1.1.0)

Packages