Skip to content
Skills Library
Programming · Writing

meta-issue-creation

/meta-issue-creation

How an agent files a GitHub issue on cipherstash repos — required structure (Background / Problem / Proposal), dumbed-down wording rules, and pre-filing checks. Use whenever drafting or filing an issue on this repo or a sibling CipherStash repo (encrypt-query-language, protectjs-ffi, …).

Repository
stack ↗
Licence
MIT
Last repository change
24.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 24.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

How an agent files a GitHub issue on cipherstash repos — required structure (Background / Problem / Proposal), dumbed-down wording rules, and pre-filing checks. Use whenever drafting or filing an issue on this repo or a sibling CipherStash repo (encrypt-query-language, protectjs-ffi, …).

Original author description

How an agent files a GitHub issue on cipherstash repos — required structure (Background / Problem / Proposal), dumbed-down wording rules, and pre-filing checks. Use whenever drafting or filing an issue on this repo or a sibling CipherStash repo (encrypt-query-language, protectjs-ffi, …).

How it works

  1. Before filing anything
  2. Structure
  3. Wording
  4. Mechanics
Original SKILL.md headings · 79 lines, 580 words
SKILL.md preview
---
name: meta-issue-creation
description: How an agent files a GitHub issue on cipherstash repos — required structure (Background / Problem / Proposal), dumbed-down wording rules, and pre-filing checks. Use whenever drafting or filing an issue on this repo or a sibling CipherStash repo (encrypt-query-language, protectjs-ffi, …).
---

# Filing issues as an agent

These are **internal** skills for agents working on CipherStash repos. They are
deliberately outside `skills/` — everything in that directory ships to
customers inside the `stash` tarball; nothing in `.claude/skills/` does.

## Before filing anything

1. **Search for existing coverage** — open *and* closed, this repo *and* the
   sibling repo the problem might belong to:

   ```bash
   gh search issues --repo cipherstash/stack "<term>" --limit 30 --json number,title,state
   ```

   A closed issue that covers your problem is a finding, not a dead end — check
   *why* it closed (linked PR? shipped artifact? silent close?) before filing a
   duplicate. Reopening with a comment often beats a new issue.
2. **Verify every mechanical claim** against code or the installed package
   before asserting it. Cite `file:line`. Separate what you **verified** from
   what is **plausible** — say which is which in the issue.
3. **Pick the right repo.** A problem caused upstream (EQL SQL, prisma-next,
   protect-ffi) gets its issue upstream, with a consumer-impact issue here only
   if this repo needs its own mitigation. Cross-reference with the full
   `owner/repo#N` form so links work from both sides.

## Structure

Required sections, in this order:

- **Background** — orient a reader who is *new to CipherStash, stack, and EQL*.
  One short paragraph: what the relevant piece does and why it exists. Define
  every product term and acronym at first use ("EQL — the SQL library we
  install into the customer's database as the `eql_v3` schema").
- **Problem** — the mechanism (what actually happens, step by step), then the
  impact (who hits it, when, how often), then why nothing catches it today.
  A concrete failure narrative beats an abstraction: "queries slow from
  instant to scan-every-row, silently" — not "performance degradation may
  occur".
- **Proposal** — numbered, concrete steps. If the full fix is large, include a
  cheap interim step that could ship first. State the failure behaviour you
  want ("fail loudly listing the statements — a loud failure beats a silent
  deletion").

Optional sections, when they earn their place:

- **Affected versions** — when the problem is version-bounded.
- **Evidence / Verification** — commands run, output observed, `file:line`.
- **Relationship to other work** — links to sibling issues, and what each one
  does/doesn't cover. After filing, leave a short cross-link comment **on the
  related issues pointing back** — links must work in both directions or one
  side is never found.

## Wording

Dumbed down, always. Assume the reader joined yesterday:

- Short sentences. Plain verbs. No internal shorthand or codenames.
- Every acronym expanded at first use, even "obvious" ones (EQL, ZeroKMS, PSL).
- Say what breaks in the user's world, not just in the code's world.
- Titles are symptom-first and name the command or package:
  `` `stash eql upgrade` silently deletes search indexes — save and restore them ``
  beats "Improve EQL upgrade robustness".
- Write `#N` **only** for a real GitHub issue or PR reference — GitHub
  autolinks every `#N`, so "step #2 of the plan" mints a bogus link to issue 2.
  Write "step 2", "item 3" instead.
- **Never** reference internal Linear issues (`CIP-…` numbers) anywhere on
  GitHub — issues, PRs, comments, commit messages. GitHub is public; Linear is
  not. GitHub refs are fine.

## Mechanics

- `gh issue create --repo cipherstash/<repo> --title '…' --label <label> --body "…"`.
- Reuse existing labels (`enhancement`, `bug`, `SDK`, …) — check with
  `gh label list` rather than inventing new ones.
- Sibling skill: [meta-pr-creation](../meta-pr-creation/SKILL.md) for the PR
  that eventually closes the issue.

Versions

The database has no other skills named meta-issue-creation.

Database snapshot: 13.11.2026 · package version be64a7f469a1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100meta-pr-creation
    How an agent authors branches, commits, and pull requests on cipherstash/stack — naming, signed commits, the changeset/skills/meta-file checklist, and PR body structure with dumbed-down wording. Use when committing work or opening/updating a PR.
  • 100issue-handler
    处理 GitHub Issue:阅读留言、调研问题、生成报告文档、回复 issue 互动。当用户说"处理 issue"、"回答 issue"、"做这个 issue"、"handle issue"、"看看 issue"时触发。
  • 100filing-follow-up-issues
    Use when creating a GitHub issue, including follow-up issues found while implementing, reviewing or planning another issue, and before running gh issue create or a GitHub MCP issue-create tool.
  • 100file-bug
    Use when filing, investigating, or root-causing a software bug. Reads the repo, drafts a detailed GitHub issue, and invokes /issue with dedup enabled.
  • 100issue-creation
    Generate issues following repository templates for GitHub or GitLab. Use when creating bug reports, feature requests, or other issues. Triggers: "create issue", "bug report", "feature request", "new issue".
  • 100tackle-issue
    Automates the process of working on GitHub issues, including branch creation, issue linking, label management, validation, changesets, and PR creation. Triggered by the command "/tackle-issue ISSUE_NUMBER".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.