Agent skill

md-issue-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.

View SKILL.md on GitHub Repository
Stars 2
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/arisng/github-copilot-fc/tree/main/skills/md-issue-writer

Metadata

Additional technical details for this skill

author
arisng
version
2.2.0

SKILL.md

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

  1. 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.

Usage

Create a new issue document via script:

bash
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:

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

To extract metadata and regenerate the index of all issues:

bash
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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

arisng/github-copilot-fc

openspec-propose

Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.

2 0
Explore
arisng/github-copilot-fc

openspec-archive-change

Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.

2 0
Explore
arisng/github-copilot-fc

openspec-explore

Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.

2 0
Explore
arisng/github-copilot-fc

openspec-apply-change

Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.

2 0
Explore
arisng/github-copilot-fc

fleet

Multi-iteration parallel subagent orchestrator for Kimi Code CLI with streamlined observability, automated documentation, and atomic commits. Use when orchestrating complex work across multiple subagents, enabling parallel execution, or when explicitly requesting fleet mode with '/flow:fleet'. Integrates diataxis documentation and git-atomic-commit workflow.

2 0
Explore
arisng/github-copilot-fc

github-pages-deploy

Deploy a static HTML file or static site directory to GitHub Pages. Use when the user wants a durable GitHub-hosted URL for a static page, diagram, report, or generated site, and can provide GitHub authentication via GITHUB_TOKEN or GH_TOKEN.

2 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results