skills.rest
praveenvijayan
praveenvijayanCOMMUNITY
Explore all skills by this author →
GitHub

ratchet-sync

Compiles plan markdown files into GitHub issues using a local Node.js sync script.

2|Updated Jun 13, 2026
Search Tags:#markdown#github issues#node.js#idempotent#gh cli#issue automation#plan sync
One-click install
npx skills add https://github.com/praveenvijayan/Ratchet --skill ratchet-sync-praveenvijayan
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: ratchet-sync
Source: https://github.com/praveenvijayan/Ratchet/tree/main/plugin/skills/ratchet-sync
Command: npx skills add https://github.com/praveenvijayan/Ratchet --skill ratchet-sync-praveenvijayan

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When working outside the normal planning-PR flow (for example on an unprotected main branch or during fast solo iteration), plan files in plan/.md do not automatically become GitHub issues. This Skill runs the deterministic plan-sync compiler locally so issues are created or updated immediately from your working tree, without waiting for a merge. ## Core Features & Use Cases - Local plan compilation: Runs scripts/plan-sync.mjs against plan/.md to create or update GitHub issues directly from the working tree. - Preflight validation: Checks for a usable token (GITHUB_PAT in .env or an authenticated gh CLI), Node.js 20+, and the presence of the sync script before running. - Idempotent execution: Safe to run repeatedly; reports how many issues were CREATEd, UPDATEd, held (HOLD), or skipped (SKIP) with reasons. - Use Case: You are iterating solo on a side project with an unprotected main branch and want your newly written plan files turned into tracked GitHub issues right now, without opening a planning PR. ## Quick Start Ask the agent to sync your local plan files into GitHub issues now using the local no-PR path.

Frequently Asked Questions about ratchet-sync

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create GitHub issues from markdown plan files?▼

Run the plan-sync.mjs script from the repository root with a GitHub token and GITHUB_REPOSITORY set. It compiles plan/*.md files into issues, reporting CREATE, UPDATE, HOLD, and SKIP outcomes for each file.

When should I use local plan sync instead of the planning PR?▼

Use the local sync only when you are not using the planning-PR flow, such as on an unprotected main branch or during fast solo iteration. The normal path is merging the rolling planning PR, which runs plan-sync on main automatically.

What credentials does plan sync need for GitHub?▼

It needs a token from GITHUB_PAT in a .env file, an existing GITHUB_TOKEN environment variable, or an authenticated gh CLI session as fallback. The token value is never printed during execution.

Why was my plan file skipped during sync?▼

A file is skipped (SKIP) when it is missing a required title or priority field. This is a plan file problem, not a script problem, so fix the plan/*.md content rather than modifying the script.

Is it safe to run plan sync multiple times?▼

Yes, the sync is idempotent and safe to run repeatedly. It only creates or updates issues from plan files and never commits, pushes, merges, or closes anything.

Related Skills

Explore More Software Engineering Skills→
mikersaysmikersays

plan-add

Generates markdown files for planning items with customizable metadata and READMEs.

Community
Intermediate
NVIDIANVIDIA
3.4k

release-cherry-pick

Cherry-pick labeled merged pull requests into release branches via GitHub CLI.

Official
Advanced
infinitioninfinition
33

github-auth

Configure GitHub authentication using personal access tokens, SSH keys, or the gh CLI.

Community
Intermediate
mistakenotmistakenot

complete-task

Finalizes a feature branch and merges its pull request to main.

Community
Intermediate