ai-issue
$
npx mdskill add arcasilesgroup/ai-engineering/ai-issueCreates GitHub or Azure work items with one command.
- Generates project tasks from natural language requests.
- Integrates with GitHub Projects v2 and Azure DevOps.
- Reads provider settings from the manifest configuration.
- Returns a clickable link to the newly created item.
SKILL.md
.github/skills/ai-issueView on GitHub ↗
---
name: ai-issue
description: "Creates a project work-item (issue / task / story) on the user's configured board: routes by manifest `work_items.provider` (GitHub Projects v2 or Azure DevOps), composes title + body + labels, attaches to the active board, and confirms a clickable link. Trigger for 'open an issue', 'file a bug', 'create a task', 'add this to the backlog', 'log a work item'. Not for upstream framework bugs (use /ai-engineering-issue); not for board configuration (use /ai-board discover); not for committing code (use /ai-commit)."
effort: cheap
argument-hint: "<title> [--body <text>] [--labels a,b] [--dry-run]"
mode: agent
tags: [work-items, board, issue, github, azure_devops]
requires:
bins:
- gh
model_tier: haiku
mirror_family: copilot-skills
generated_by: ai-eng sync
canonical_source: .claude/skills/ai-issue/SKILL.md
edit_policy: generated-do-not-edit
---
# Issue Creation
Discoverable wrapper around the project board: composes a work-item, routes by manifest provider, attaches to the configured GitHub Project (or Azure Boards area path), confirms the URL.
```
/ai-issue "<title>" # default body from session context
/ai-issue "<title>" --body "<text>" # explicit body
/ai-issue "<title>" --labels bug,p1 # apply labels
/ai-issue "<title>" --dry-run # print the command, do not invoke
```
## Quick Start
1. Confirm the active provider in `.ai-engineering/manifest.yml` under `work_items.provider` — either `github` or `azure_devops`.
2. Confirm CLI auth: `gh auth status` for GitHub, `az account show` for Azure DevOps.
3. Invoke `/ai-issue "<title>"` — the skill composes title + body + labels and attaches to the configured board.
## Workflow
Principles applied: §10.1 KISS (thin wrapper over board plumbing; no rediscovery of provider state); §10.4 DRY (reuses `manifest.yml work_items` config rather than redefining provider routing per skill); §10.6 SDD (implements D-134-02 — discoverable issue surface promoted to first-class).
1. **Read configuration.** Open `.ai-engineering/manifest.yml` and locate the `work_items:` section. Required keys: `provider` (`github` or `azure_devops`). For GitHub also read `github_project.{owner,number}` and `github.team_label`. For Azure DevOps read `azure_devops.area_path` and `process_template`. If the section is absent or empty, refuse with a remediation line ("manifest missing `work_items` config — run `/ai-board discover` first") and exit non-zero.
2. **Preflight auth.** Run `gh auth status` (GitHub path) or `az account show` (Azure path). On non-zero exit, refuse with the remediation hint ("run `gh auth login`" / "run `az login`") and exit. Never proceed with an unauthenticated CLI.
3. **Compose title and body.** Title comes from `$ARGUMENTS` (or interactive prompt if absent). Body defaults to the session-context summary (recent commits, active spec, error logs) — overridable with `--body "<text>"`. Apply labels from `--labels` plus the configured `work_items.github.team_label`. Honour the `--dry-run` flag by printing the planned shell command without invoking.
4. **GitHub path.** Shell `gh issue create --title "<t>" --body "<b>" --label "<l1>,<l2>"`. Then attach to the project: `gh project item-add <number> --owner <owner> --url <issue-url>`. Capture the returned issue URL.
5. **Azure DevOps path.** Shell `az boards work-item create --title "<t>" --type "Task" --area "<area_path>" --description "<b>"`. Then set fields per `custom_fields` table in manifest. Capture the returned work-item ID + URL.
6. **Report outcome.** Print the issue URL (or work-item ID) and the configured board phase ("Backlog" by default — the state mapping comes from `work_items.state_mapping.refinement`).
7. **Audit.** Emit a `framework_event` with `kind: work_item_created`, `component: ai-issue`, `detail: {provider, issue_id, url}`. The event chains into the standard audit pipeline.
## Examples
### Example 1 — GitHub Projects v2 issue
User: "open an issue: pre-commit hook times out on macOS arm64"
```
/ai-issue "pre-commit hook times out on macOS arm64" --labels bug,p1
```
Skill reads `work_items.provider: github`, runs `gh auth status` (green), composes the body from recent session context, shells `gh issue create --title "..." --label "bug,p1,team:core"`, attaches to GitHub Project `arcasilesgroup/4`, prints the issue URL.
### Example 2 — Azure DevOps task with dry-run preview
User: "create a task to wire up the new spec gate, but show me the command first"
```
/ai-issue "wire up spec gate in /ai-brainstorm" --dry-run
```
Skill reads `work_items.provider: azure_devops`, prints the planned `az boards work-item create --title "..." --type "Task" --area "Project\TeamName"` invocation and exits without calling Azure.
## Quick Reference
| Goal | Command |
|------|---------|
| Create issue with session-context body | `/ai-issue "<title>"` |
| Provide explicit body | `/ai-issue "<title>" --body "<text>"` |
| Apply labels | `/ai-issue "<title>" --labels bug,p1` |
| Preview without invoking | `/ai-issue "<title>" --dry-run` |
## Common Mistakes
- Calling `/ai-issue` without running `/ai-board discover` first — the manifest needs `work_items.provider` populated before this skill can route.
- Bypassing the auth preflight — an unauthenticated `gh` / `az` will produce a partial / confusing failure; the skill refuses on purpose.
- Confusing this skill with `/ai-engineering-issue` — that one files upstream framework bugs and runs strict seven-vector redaction. `/ai-issue` is for **your project's** board.
## Integration
Called by: user directly. Reads: `.ai-engineering/manifest.yml` (`work_items` section). Writes: project board (GitHub Projects v2 item OR Azure Boards work item). Audited: `framework_event kind=work_item_created`. Pairs with: `/ai-board discover` (one-time provider configuration), `/ai-board sync` (lifecycle state transitions on existing items). See also: `/ai-engineering-issue` for upstream framework bug reports with strict redaction.
$ARGUMENTS
More from arcasilesgroup/ai-engineering
- ai-adviseProactive governance advisor — checks standards, decisions, and quality trends during development. Always advisory, NEVER blocks. Three modes: `advise` (post-edit), `gate` (pre-dispatch), `drift` (on-demand decision audit). Trigger for 'governance check', 'advise on this change', 'check for drift', 'is this aligned with active decisions', 'shift-left advisory'. Not for blocking gates — use /ai-verify. Not for narrative code review — use /ai-review.
- ai-analyze-permissionsUse when Claude Code keeps asking to approve commands you have already approved, when settings.local.json has grown large, or when you want to consolidate permission grants into wildcard patterns. Trigger for 'too many permission prompts', 'clean up permissions', 'audit my settings', 'consolidate allow rules'. Claude Code only — not available in GitHub Copilot, Antigravity, or Codex.
- ai-animationDesigns motion, transitions, and micro-interactions for UI components: spring animations, gestures, easing, staggers — taste-driven detail compounding. Trigger for 'animate this', 'add transitions', 'micro-interactions for', 'gesture design', 'swipe to dismiss', 'easing for this', 'stagger the'. Not for design systems; use /ai-design instead. Not for visual art; use /ai-visual instead. Not for testing animation code; use /ai-test instead.
- ai-autopilotDelivers large multi-concern specs and backlog runs autonomously: decomposes specs into sub-specs (or normalizes work items into a backlog DAG), deep-plans with parallel agents, builds a dependency DAG, implements in waves, runs a single final quality loop with one bounded quality-remediation pass (verify+guard+review on full changeset), delivers via PR. Trigger for 'implement spec-NNN end to end', 'autopilot this', 'autonomous delivery', 'decompose and ship', 'run the backlog', 'execute these GitHub issues', 'process the sprint backlog'. Invocation is the approval gate. Not for small or single-concern tasks; use /ai-build instead. Not for ambiguous requirements; use /ai-brainstorm first.
- ai-boardOperates the project board (GitHub Projects v2 or Azure DevOps): discovers configuration after install (fields, state mappings, process templates) and syncs work-item state at lifecycle transitions. Trigger for 'set up the board', 'configure our ADO board', 'discover board fields', 'move this issue to in-review', 'update the board', 'mark as in progress', 'sync the work item state'. Two subcommands: `discover` (post-install configuration write) and `sync` (lifecycle state transitions). Auto-invoked via `sync` by /ai-brainstorm, /ai-build, and /ai-pr; fail-open. Not for backlog execution; use /ai-autopilot --backlog instead.
- ai-brainstormForces rigorous design interrogation BEFORE any code: explores approaches, surfaces ambiguity, gathers evidence, produces an approved spec that becomes the contract for /ai-plan. Trigger for 'lets add X', 'how should we handle Y', 'whats the best approach', 'I am thinking about', 'what should we build for'. Not for existing approved specs; use /ai-plan instead. Not for execution; use /ai-build instead.
- ai-branch-cleanupCleans branches safely: switches to the default branch, prunes merged and squash-merged branches, syncs to remote, sweeps stale specs, rotates `.ai-engineering/runtime/` per retention policy. Trigger for 'tidy up', 'tidy branches', 'sync to main', 'delete old branches', 'start fresh', 'rotate runtime'. Auto-invoked by /ai-pr after merge. Not for committing changes; use /ai-commit instead. Not for code-level dead-code removal; use /ai-simplify instead.
- ai-buildCanonical implementation gateway: reads approved plan.md, resolves stack from manifest, deterministic-routes each task to its adapter, dispatches the build agent in an isolated worktree, runs TDD self-validation per task, then a single final quality loop with one bounded quality-remediation pass on the full changeset before /ai-pr. Trigger for 'go', 'start building', 'execute the plan', 'implement it', 'lets do this', 'build the plan', 'resume', 'continue'. Not without an approved plan; run /ai-plan first. Not for multi-concern specs needing decomposition; use /ai-autopilot instead. Not for a single function or subcomponent; use /ai-code.
- ai-codeWrites production code that satisfies stack-context standards on the first pass: interface-first design, backward-compatibility checks, lightweight self-review. Trigger for 'implement this', 'write the code for', 'add X to Y', 'build this function', 'make this work'. Not for tests; use /ai-test instead. Not for debugging; use /ai-debug instead. Not for refactoring; use /ai-simplify instead. Not for executing an approved plan end-to-end; use /ai-build (the gateway).
- ai-commitRuns the governed commit pipeline: auto-branches from protected, stages selectively, formats and lints, scans for secrets, gates docs, composes a conventional message, pushes. Trigger for 'commit my changes', 'save my work', 'push this to remote', 'stage these files', 'ship it'. Not for opening a PR; use /ai-pr instead. Not for branch hygiene; use /ai-branch-cleanup instead.