refactor(stack): remove mergify stack skill command

README.md

@@ -44,19 +44,26 @@ mergify ci --help
 mergify freeze --help
 ```
 
-## Claude Code Plugin
+## AI Agent Skills
 
-Mergify CLI is available as a [Claude Code
-plugin](https://docs.anthropic.com/en/docs/claude-code/plugins), providing AI
-skills for managing stacked PRs and Git workflows.
+Mergify CLI provides AI skills for managing stacked PRs and Git workflows,
+compatible with [Claude Code](https://docs.anthropic.com/en/docs/claude-code),
+[Cursor](https://cursor.sh), and [many other AI
+agents](https://skills.sh).
 
-### Install from the official marketplace
+### Install via npx (all agents)
+
+```shell
+npx skills add Mergifyio/mergify-cli
+```
+
+### Install as a Claude Code plugin
 
 ```shell
 claude /plugin install mergify@claude-plugins-official
 ```
 
-### Install from this repository
+Or from this repository:
 
 ```shell
 claude /plugin marketplace add https://github.com/Mergifyio/mergify-cli

mergify_cli/stack/cli.py

@@ -21,7 +21,6 @@
 from mergify_cli.stack import push as stack_push_mod
 from mergify_cli.stack import reorder as stack_reorder_mod
 from mergify_cli.stack import setup as stack_setup_mod
-from mergify_cli.stack import skill as stack_skill_mod
 
 
 def trunk_type(
@@ -441,11 +440,6 @@ async def github_action_auto_rebase(ctx: click.Context) -> None:
     )
 
 
-@stack.command(help="Output the AI skill for the Mergify stack workflow")
-def skill() -> None:
-    click.echo(stack_skill_mod.get_skill_content(), nl=False)
-
-
 @stack.command(name="list", help="List the stack's commits and their associated PRs")
 @click.pass_context
 @click.option(

skills/mergify-stack/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: mergify-stack
+description: Use Mergify stacks for git push, commit, branch, and PR creation. ALWAYS use this skill when pushing code, creating commits, creating branches, or creating PRs. Triggers on push, commit, branch, PR, pull request, stack, git.
+---
+
+# Mergify Stack Workflow
+
+## Stack Philosophy
+
+A branch is a stack. Keep stacks short and focused:
+- A stack should only contain commits that **depend on each other**
+- Rationale: longer stacks take longer to merge
+
+**Proactive stack management:**
+- If an existing stack can be split into independent stacks, offer to do so
+- When asked to do something new: if it can be done on a separate branch, either do so or ask if in doubt
+- Default to creating a new branch for unrelated changes
+
+## Core Conventions
+
+- **Push**: Use `mergify stack push` (never `git push`)
+- **Fixes**: Use `git commit --amend` (never create new commits to fix issues)
+- **Mid-stack fixes**: Use `git rebase -i` to edit the specific commit, amend it, continue rebase, then `mergify stack push`
+- **Commit titles**: Follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`)
+- **PR title & body**: `mergify stack` copies the commit message title to the PR title and the commit message body to the PR body — so write commit messages as if they were PR descriptions. **Everything that should appear in the PR (ticket references, context, test plans) MUST go in the commit message.**
+- **Ticket references**: Include ticket/issue references (e.g., `MRGFY-1234`, `Fixes #123`) in the commit message body, not added separately to the PR.
+- **PR lifecycle is fully managed by `mergify stack`**: NEVER edit PR titles, bodies, or labels with `gh pr edit` or the GitHub MCP — they will be overwritten on the next push. NEVER close or merge PRs manually — `mergify stack` handles the entire PR lifecycle (creation, updates, and cleanup).
+- **Draft PRs**: NEVER mark a PR as ready-for-review — all PRs stay as drafts. The user will manually move them out of draft after reviewing.
+- **Each commit must pass CI independently**: Every commit in a stack becomes its own PR. Each PR runs CI separately, so every commit must be self-contained — it must compile, pass linters, and pass tests on its own without depending on later commits in the stack. When formatting or linting fixes are needed, they must be included in the commit that introduced the issue, not deferred to a later commit.
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `git push` | `mergify stack push` | Git push bypasses stack management and breaks PR relationships |
+| New commit to fix lint/typo | `git commit --amend` (HEAD) or `git commit --fixup <SHA>` + `git rebase --autosquash` (mid-stack) | Each commit = a PR; fix commits create unwanted extra PRs |
+| `gh pr edit --title "..."` | Edit the commit message, then `mergify stack push` | PR title/body are overwritten from commit messages on every push |
+| `gh pr merge` or `gh pr close` | PR lifecycle is fully managed — do nothing | PR lifecycle is fully managed by the stack tool |
+| `git commit` on `main` | `mergify stack new <name>` first | `mergify stack push` will fail on the default branch |
+| Deferring lint fixes to a later commit | Include the fix in the commit that caused it | Each commit runs CI independently; later commits won't save earlier ones |
+
+## Commands
+
+```bash
+mergify stack new NAME       # Create a new stack/branch for new work
+mergify stack push           # Push and create/update PRs
+mergify stack list           # Show commit <-> PR mapping for current stack
+mergify stack list --json    # Same, but machine-readable JSON output
+```
+
+Use `mergify stack list` to see which commits have been pushed, which PRs they map to, and whether the stack is up to date with the remote. This is the go-to command to understand the current state of a stack. Use `--json` when you need to parse the output programmatically.
+
+## CRITICAL: Check Branch Before ANY Commit
+
+**BEFORE staging or committing anything**, always check the current branch and assess stack state:
+
+```bash
+git branch --show-current
+mergify stack list
+```
+
+- If you're on `main` (or the repo's default branch): you **MUST** create a feature branch first
+- **NEVER commit directly on `main`** — `mergify stack push` will fail
+- This check must happen before `git add`, not after `git commit`
+
+## Starting New Work
+
+When asked to start a new piece of work, create a new feature, or work on something unrelated to the current stack:
+
+1. **Check current branch**: `git branch --show-current`
+2. **Create a new stack**: `mergify stack new <branch-name>`
+   - Use descriptive branch names following the pattern: `type/short-description` (e.g., `feat/add-login`, `fix/memory-leak`)
+3. **Make commits** following conventional commits
+4. **Push**: `mergify stack push`
+
+## Adding to Existing Stack
+
+When continuing work on an existing feature branch:
+
+1. **Check current branch**: `git branch --show-current`
+   - If on the right branch: proceed with commits
+   - If on `main`: switch to the feature branch first with `git checkout <branch>` or create a new stack
+
+## Conflict Resolution
+
+When a rebase causes conflicts (during `git rebase -i` or `mergify stack push`):
+
+1. Resolve conflicts in your editor
+2. Stage resolved files with `git add`
+3. Continue with `git rebase --continue`
+
+To abort instead: `git rebase --abort`
+
+After resolving, run `mergify stack push` to sync the updated stack.