How does the skill link a local file to a GitHub issue?

It uses a hidden HTML comment marker ( ) within the GitHub issue body to track the relationship between the document and the issue.

Does this skill modify my local Markdown files?

No, local documents remain the source of truth. The skill only reads your local files to create or update the corresponding issues on GitHub.

How are GitHub labels handled?

The skill automatically maps document statuses to labels; for example, proposals are tagged with 'type:rfc' and plans with 'type:plan', along with their current lifecycle status.

What are the prerequisites for using this skill?

You must have the GitHub CLI (gh) installed and authenticated on your machine, and your local repository must have a configured GitHub remote.

Can I preview changes before they are pushed to GitHub?

Yes, you can use the --dry-run flag with the /sync-issues command to see exactly what would be created or updated without making actual changes.

Principled GitHub Issue Sync

Name: Principled GitHub Issue Sync
Author: alexnodeland

byalexnodeland

•

Collaboration Tools

Synchronizes local proposal and plan documents with GitHub issues to maintain a unified project roadmap and source of truth.

Principled GitHub Issue Sync is designed to bridge the gap between local specification-driven development and team project management. This skill automates the creation and updating of GitHub issues directly from your local Markdown proposals and plans, ensuring that your documentation remains the single source of truth while keeping stakeholders informed. By utilizing hidden sync markers and the GitHub CLI, it maintains bidirectional references and automatically maps document statuses to appropriate GitHub labels, significantly reducing the manual overhead of managing project lifecycles.

Key Features

01Batch synchronization support for entire proposal and plan directories

02Smart mapping of document status to GitHub labels (e.g., type:rfc, type:plan)

03Automated creation and updating of GitHub issues from Markdown documents

04Bidirectional reference tracking using hidden HTML sync markers

053 GitHub stars

06Dry-run mode to preview issue changes before execution

Use Cases

01Automating label management and status updates based on local document lifecycle changes

02Synchronizing local project plans with GitHub milestones to maintain public roadmaps

03Converting technical RFCs and design docs into trackable GitHub issues for team review

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add alexnodeland/principled sync-issues

For use in Claude.ai and ChatGPT

Download Skill