How do I install the Issue Md Writer skill?

Run npx skillmds@latest add arisng/issue-md-writer in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Issue Md Writer safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Issue Md Writer?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Issue Md Writer free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Issue Md Writer?

arisng (@arisng) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Issue Md Writer by arisng — Agent Skill

Name: Issue Md Writer
Author: arisng

Issue Md Writer

Create and draft markdown-based issue documents (bug reports, feature plans, RFCs, ADRs, tasks, retrospectives) in the top-level `.issues/` folder. Use this skill whenever you need to document software issues, feature proposals, architectural decisions, work items, or post-mortems. Includes templates, metadata indexing, and structured YAML frontmatter. Different from issue tracker systems — this is for archival, decision-making, and knowledge base documents.

arisng 18da4d1 10 files · 42.7 KB Updated Sep 17, 2026

File contents

MD Issue Writer

Overview

This skill enables the creation of concise, one-page technical documents for software issues, features, decisions, and work items. Each document follows a standardized YAML frontmatter and markdown structure, making them discoverable and indexable across the knowledge base.

When to Use Each Document Type

Use this decision tree to select the right template:

Situation	Document Type	Purpose
Something broke or isn't working	Bug Report	Root cause analysis, prevention, lessons learned
Build/ship a new capability	Feature Plan	Goals, requirements, implementation approach, risks
Need consensus on architectural direction	RFC	Proposal, motivation, design, alternatives, Q&A
Made a major technical decision	ADR	Document the decision, context, and consequences
Have specific work to accomplish	Task	Objectives, acceptance criteria, checklist
Learned something from an incident/project	Retrospective	What happened, what went well, lessons, actions

Workflow

Choose the document type using the decision tree above or by reviewing the templates in templates/.
Gather required metadata: title, description, severity (if applicable), status, author (if applicable).
Generate the document using the provided script or by copying a template into the new .issues/ directory (it will be created automatically).
Fill in the content following the template structure.
(Optional) Index all documents by running the metadata extraction script to keep the central index current.

Usage

Create a new issue document via script:

python scripts/create_issue.py --type "Bug" --title "Fix login timeout" --description "Users are logged out after 5 minutes" --severity "High"

Or copy a template directly:

cp templates/<type>.md .issues/<date>_<slug>.md

To extract metadata and regenerate the index of all issues:

python scripts/extract_issue_metadata.py

Template Reference

Each issue type has its own reference file in templates/:

bug-report.md — Incident analysis with root cause, solution, and prevention steps
feature-plan.md — Feature proposal with goals, requirements, and implementation approach
rfc.md — RFC proposal with motivation, design, alternatives, and open questions
adr.md — Architecture decision record for major technical choices
task.md — Work item with objectives, acceptance criteria, and references
retrospective.md — Post-incident or post-project learning document

See templates/index.md for a complete overview and quick-reference guide.

Resources

scripts/

create_issue.py — Generate issue documents based on templates
extract_issue_metadata.py — Extract metadata and regenerate the index

templates/

index.md — Quick reference and overview of all template types
bug-report.md, feature-plan.md, rfc.md, adr.md, task.md, retrospective.md — Individual templates

---name: issue-md-writerdescription: Create and draft markdown-based issue documents (bug reports, feature plans, RFCs, ADRs, tasks, retrospectives) in the top-level `.issues/` folder. Use this skill whenever you need to document software issues, feature proposals, architectural decisions, work items, or post-mortems. Includes templates, metadata indexing, and structured YAML frontmatter. Different from issue tracker systems — this is for archival, decision-making, and knowledge base documents.---# MD Issue Writer## OverviewThis skill enables the creation of concise, one-page technical documents for software issues, features, decisions, and work items. Each document follows a standardized YAML frontmatter and markdown structure, making them discoverable and indexable across the knowledge base.## When to Use Each Document TypeUse this decision tree to select the right template:| **Situation** | **Document Type** | **Purpose** ||---|---|---|| Something broke or isn't working | **Bug Report** | Root cause analysis, prevention, lessons learned || Build/ship a new capability | **Feature Plan** | Goals, requirements, implementation approach, risks || Need consensus on architectural direction | **RFC** | Proposal, motivation, design, alternatives, Q&A || Made a major technical decision | **ADR** | Document the decision, context, and consequences || Have specific work to accomplish | **Task** | Objectives, acceptance criteria, checklist || Learned something from an incident/project | **Retrospective** | What happened, what went well, lessons, actions |## Workflow1. **Choose the document type** using the decision tree above or by reviewing the templates in `templates/`.2. **Gather required metadata**: title, description, severity (if applicable), status, author (if applicable).3. **Generate the document** using the provided script or by copying a template into the new `.issues/` directory (it will be created automatically).4. **Fill in the content** following the template structure.5. **(Optional) Index all documents** by running the metadata extraction script to keep the central index current.## UsageCreate a new issue document via script:```bashpython scripts/create_issue.py --type "Bug" --title "Fix login timeout" --description "Users are logged out after 5 minutes" --severity "High"```Or copy a template directly:```bashcp templates/<type>.md .issues/<date>_<slug>.md```To extract metadata and regenerate the index of all issues:```bashpython scripts/extract_issue_metadata.py```## Template ReferenceEach issue type has its own reference file in `templates/`:- **bug-report.md** — Incident analysis with root cause, solution, and prevention steps- **feature-plan.md** — Feature proposal with goals, requirements, and implementation approach- **rfc.md** — RFC proposal with motivation, design, alternatives, and open questions- **adr.md** — Architecture decision record for major technical choices- **task.md** — Work item with objectives, acceptance criteria, and references- **retrospective.md** — Post-incident or post-project learning documentSee `templates/index.md` for a complete overview and quick-reference guide.## Resources### scripts/- `create_issue.py` — Generate issue documents based on templates- `extract_issue_metadata.py` — Extract metadata and regenerate the index### templates/- `index.md` — Quick reference and overview of all template types- `bug-report.md`, `feature-plan.md`, `rfc.md`, `adr.md`, `task.md`, `retrospective.md` — Individual templates

Frequently asked questions