# Issue File

> Create or update GitHub issue from markdown file using --body-file Use when this capability is needed.

- Skill: `tomevault-io/issue-file` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/issue-file`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/issue-file/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/issue-file

---


# /issue-file

Create or update a GitHub issue using a markdown file as the body.

## Usage

```
/issue-file ISSUE-feature-name.md
```

**CRITICAL: Use the `--body-file` flag to ensure the ENTIRE contents of the file become the issue body verbatim.**

## Workflow

### Step 1: Determine the file path

- If `$ARGUMENTS` is provided, use that as the file path
- Otherwise, check if the file path is clearly determinable from the current conversation context
- If unclear, ask the user which file to use

### Step 2: Check for existing issue context

Search the recent conversation history for:
- Issue numbers mentioned in previous `/work-issue` commands
- Issue numbers referenced in discussion (e.g., "#123", "issue 123")
- Any clear indication we're discussing a specific issue

If found, this is an UPDATE operation. Otherwise, CREATE.

### Step 3: Check for assignee context

Look for explicit mentions like:
- "this is an issue for [username]"
- "assign this to [username]"

**Do NOT auto-assign without explicit context.**

### Step 4: Extract title from file

For CREATE operations, extract the title from the file:
1. Read the first line of the file
2. If it starts with `# ` (markdown h1 heading), strip the `# ` prefix and use as title
3. If no markdown heading, use the filename (without extension) as the title

### Step 5: Execute

**Update** (issue number found in context):
```bash
gh issue edit <number> --body-file <file>
```

**Create** (no issue number):
```bash
gh issue create --title "<extracted title>" --body-file <file>
```

**Create with assignee** (if explicitly mentioned):
```bash
gh issue create --title "<extracted title>" --body-file <file> --assignee <username>
```

**IMPORTANT:**
- NEVER use `--label` flags
- NEVER ask the user for the title — extract it from the file or filename
- Use `--body-file` (or `-F`) flag exclusively for the body
- Only add `--assignee` if explicitly mentioned in conversation context

### Step 6: Open the file for review

After the gh command succeeds, open the file so the user can review what was submitted (whether called standalone or chained from `/issue-check`):

```bash
if [ -n "$TMUX" ]; then
    tmux display-popup -w 80% -h 80% -E -- less <file>
elif [ "$TERM_PROGRAM" = "zed" ]; then
    zed <file>
fi
```

Then stop and wait for the user. Do not summarize the file contents.

### Step 7: Report results

After the user closes the file (or if neither tmux nor Zed was detected), report:
- Success/failure status
- Issue number and URL
- Whether it was a create or update operation

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/matsen) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->