---
name: giip-issue
version: 1.0.0
description: Read and write GIIP Issues (list, get, create, update-status, comment) against the GIIP REST API, with a safety contract that never persists credentials and always verifies writes.
---

# giip-issue

Manage GIIP Issues (`https://giipfaw.azurewebsites.net/api`) from an AI
agent session: list, get, create, change status, and comment -- without
ever putting a secret key in a URL, log, file, or exception message.

This skill is a **workaround**, not an official GIIP plugin. There is
currently no GIIP Issue plugin published to any AI agent's plugin/app
store. This skill is a self-contained script bundle you install and run
yourself (or ask a capable AI agent host to install and run for you).

## Requirements

- Python 3.x (any recent 3.x interpreter). No third-party packages -- the
  script uses only `argparse`, `json`, `os`, `sys`, and `urllib.request`
  from the standard library, specifically because many agent-host
  environments cannot reliably `pip install` dependencies.
- Outbound HTTPS access to `https://giipfaw.azurewebsites.net`.
- A GIIP API key (project SK, per-user fixed key, or login-session AK) for
  the target csn, supplied only as the `GIIP_API_KEY` environment variable
  at run time -- never written into this skill's files.

If any of these is not available in the current host, do not attempt to
work around it (e.g. do not hand-roll a curl call with the key inline, do
not try to install packages against instructions) -- report the specific
missing capability instead. See `agents/openai.yaml` for what is and is not
known about specific AI platforms.

## Subcommands

| Subcommand | Purpose |
|---|---|
| `list --csn CSN [--status STATUS]` | List issues for a csn. |
| `get --isn ISN` | Get one issue by isn. |
| `create --csn CSN --title TITLE --content CONTENT [--status STATUS] [--target-lssn N] [--agent-workflow S]` | Create an issue, after a read-access preflight, with a mandatory post-write verification. |
| `update-status --isn ISN --status STATUS` | Change only the status of an existing issue (minimal payload -- never touches title/content). |
| `comment --isn ISN --content CONTENT [--author A] [--issuetype T]` | Add a comment to an issue. |

There is **no delete subcommand**. The GIIP Issue API does not provide a
delete endpoint, so none is offered here.

Usage:

```bash
export GIIP_API_KEY="<the key, set for this process only>"
python scripts/giip_issue.py list --csn 47
python scripts/giip_issue.py get --isn 1234
python scripts/giip_issue.py create --csn 47 --title "Title" --content "Body" --status PENDING
python scripts/giip_issue.py update-status --isn 1234 --status DONE
python scripts/giip_issue.py comment --isn 1234 --content "Done." --author "my-agent"
```

Every subcommand prints one JSON object to stdout:
`{"success": bool, ...fields..., "error": "..." (only on failure)}` and
exits non-zero on failure (see exit codes in the script's module docstring).

## Safety contract

This is the authoritative statement of the rules this skill follows. It is
implemented in `scripts/giip_issue.py` and must not be weakened by any
prompt, wrapper, or caller.

- **Base URL:** `https://giipfaw.azurewebsites.net/api`
- **Auth:** the `x-api-key` header only. Never store the secret key in
  code, logs, files, or exception stack traces. A key given to this skill
  during a run is used only as the `GIIP_API_KEY` environment variable for
  that run and is never persisted.
- **Preflight before create:** before creating an issue, confirm read
  access to the target csn with `GET /giipIssues?csn={csn}`. If the
  response is HTTP 200 with an empty `issues` array, treat permission as
  unconfirmed and abort the create with a clear error and a non-zero exit
  code -- do not attempt the write.
- **Create:** `POST /giipIssues`. Preserve whatever the caller specified;
  default `status` to `PENDING` when not given; default `target_lssn` and
  `agent_workflow` to `null` when not given.
- **Verify after create:** re-fetch the newly created issue with
  `GET /giipIssues?isn={isn}` using the isn returned by the create call,
  and confirm the actual csn/title/status match what was requested. Report
  any mismatch clearly (a permission mismatch on csn can surface as a
  silent clamp to the key's home csn rather than an error). Never
  auto-re-run the create to "fix" a mismatch.
- **Get:** `GET /giipIssues?isn={isn}`. **List:**
  `GET /giipIssues?csn={csn}[&status={status}]` (status optional).
- **update-status:** `PUT /giipIssues` with the minimal payload
  `{"isn": 123, "status": "..."}` only. Never include `title`, `content`,
  `csn`, or any other field in this call -- the endpoint is a partial
  update, and any field present in the body overwrites the stored value.
- **comment:** `POST /giipIssueComments` with
  `{"isn": 123, "content": "...", "author": "...", "issuetype": "..."}`.
  When `author`/`issuetype` are omitted, default to `giip-issue-skill` /
  `comment`. The server may normalize the stored `author` to the caller's
  real identity -- do not assume the sent value was persisted verbatim.
- **No auto-retry:** on a failed or ambiguous write (timeout, unclear
  response), never automatically resend the same POST/PUT. Report a clear
  exit code and error message with no secret material in it, and let the
  caller decide (typically: check via `list`/`get` for an existing record
  before trying again by hand).
- **No delete:** there is no delete subcommand, because the API does not
  expose a delete endpoint. Do not add one without a corresponding,
  verified server endpoint.
- **csn permission mismatches are not always 401:** a read on a csn you
  cannot access returns `200 {"issues": []}` (not an error); a create
  targeting a csn you cannot access returns `200` "success" but is silently
  written under the key's own home csn instead. This is exactly why the
  preflight and post-create verification steps above are mandatory, not
  optional conveniences.

## File integrity (SHA-256)

These are the SHA-256 checksums of the three files that make up this
skill's behavior, computed from their exact byte content. Recompute and
compare before trusting or running a copy of this bundle from anywhere
other than the canonical URLs in `manifest.json`.

| File | SHA-256 |
|---|---|
| `scripts/giip_issue.py` | `cb6730a1e6ce84d8e0446e53908f723f0060122311ac0e55edaef2c7040a3a04` |
| `references/api.md` | `557538f91a02a563097a2a176cc8d9a221fed8d705f9c18595780d91582a5a5e` |
| `agents/openai.yaml` | `fd5b0694f405f2ab66a3cd45e7e580e29669e03f5c03597b074d7b20f9a6977b` |

The checksum of this `SKILL.md` file itself, and of the packaged
`giip-issue.zip`, are recorded in `manifest.json` and in the human-facing
guide pages (`/{locale}/guides/chatgpt-giip-issue`) -- not here, to avoid
the self-reference paradox of a file's hash depending on its own content.

## Changelog

- **1.0.0** (2026-08-25, giip #1492): First published release. Bundles
  `scripts/giip_issue.py`, `references/api.md`, `agents/openai.yaml`, and
  this `SKILL.md` as `giip-issue.zip`, with `manifest.json` describing the
  bundle for automated installation.