diagnosing-forge

Diagnose Forge installation health by validating .forge/ structure, state, hooks, and storage.

Updated Aug 27, 2026
One-click install
npx skills add https://github.com/rahulsc/forge --skill diagnosing-forge
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: diagnosing-forge
Source: https://github.com/rahulsc/forge/tree/main/skills/diagnosing-forge
Command: npx skills add https://github.com/rahulsc/forge --skill diagnosing-forge

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps identify and diagnose issues within a Forge installation, ensuring its integrity and proper functioning by running comprehensive health checks.

Core Features & Use Cases

  • Health Checks: Verifies directory structure, project.yaml validity, hook installations, and storage backend health.
  • Stale State Detection: Identifies orphaned worktrees, incomplete tasks, and zombie checkpoints.
  • Pack Integrity: Checks the validity of installed Forge packs.
  • Use Case: After encountering unexpected errors or after disruptive Git operations, run this Skill to pinpoint the exact cause of the problem within your Forge setup.

Quick Start

Run the diagnosing-forge skill to perform a full health check of the current Forge installation.

Frequently Asked Questions about diagnosing-forge

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

FAQPage Schema
How do I diagnose Forge health and state issues after a disruptive Git operation?

To diagnose Forge health issues, run a comprehensive health check that validates the .forge/ directory structure, project.yaml, hook installations, and storage backend integrity. It identifies orphaned worktrees, zombie checkpoints, and stale state, reporting problems with suggested remediation steps without auto-fixing.

What is the best way to troubleshoot an invalid Forge project.yaml configuration?

Troubleshooting an invalid Forge project.yaml involves running a diagnostic health check that validates the file's structure and configuration. The diagnostic process reports specific validation errors and provides suggested remediation steps to correct the project configuration.

How do I detect stale state and orphaned worktrees in my Forge installation?

Detecting stale state in a Forge installation requires running health checks that scan for orphaned worktrees, incomplete tasks, and zombie checkpoints. The diagnostic tool identifies these stale elements and reports them alongside suggested remediation actions.

Can I use Forge diagnostics to verify pack integrity and storage backend health?

Yes, Forge diagnostics can verify pack integrity and storage backend health. The diagnostic checks validate installed Forge packs and assess the storage backend's integrity, reporting any detected issues with recommended remediation steps to ensure proper functioning.

Does the Forge health check automatically fix detected hook installation issues?

No, the Forge health check does not automatically fix detected hook installation issues. It validates hook installations and reports any problems it finds, providing suggested remediation steps for the user to manually resolve the identified issues.