Troubleshooting
If something isn’t working, start here. For general setup help see Getting Started → Need help?.
Common errors
Section titled “Common errors”Forge reports ast-grep is unavailable
Section titled “Forge reports ast-grep is unavailable”If setup reports that ast-grep was not detected, install it to unlock the Forge tier: https://ast-grep.github.io. Re-run @Ferris SF afterward — your tier upgrades automatically.
”No brief found”
Section titled “”No brief found””Run @Ferris BS first to create a skill brief, or use @Ferris QS for brief-less generation. CS requires either a brief or a direct invocation with scope arguments.
”Ecosystem check: official skill exists”
Section titled “”Ecosystem check: official skill exists””An official skill already exists for this package. Consider installing it with npx skills add instead of generating your own — the official skill is typically better tested and kept up-to-date by the library maintainer.
Quick-tier skills have lower confidence scores
Section titled “Quick-tier skills have lower confidence scores”Quick tier reads source without AST analysis, so signatures are read directly from files rather than structurally verified. Install ast-grep to upgrade to the Forge tier for AST-verified signatures (T1 confidence) — see Capability Tiers.
Want semantic discovery for large codebases?
Section titled “Want semantic discovery for large codebases?”Install cocoindex-code to unlock the Forge+ tier. CCC indexes your codebase and pre-ranks files by semantic relevance before AST extraction, improving coverage on projects with 500+ files.
Still stuck?
Section titled “Still stuck?”- Run
@Ferris SFto check your tool availability and current tier - Check
forge-tier.yamlin your forger sidecar for your configuration - If
/bmad-helpis installed (via full BMAD Method), run it and describe your state — e.g./bmad-help my batch creation failed halfway, how do I resume? - File an issue — SKF’s health check system is the primary feedback channel, and manual issues feed the same pipeline