Troubleshooting
If something isn’t working, start here. For general setup help see Getting Started → Need help?.
Common errors
Section titled “Common errors””Setup cannot proceed: uv is not installed”
Section titled “”Setup cannot proceed: uv is not installed””Surfaced by /skf-setup On Activation when uv --version is missing on $PATH. SKF helpers depend on uv to auto-resolve their Python dependencies via PEP 723 inline metadata; bare python3 ignores that metadata and would fail later with ModuleNotFoundError: No module named 'yaml'. The probe halts the workflow up-front with one cohesive diagnostic instead of letting five steps each fail individually.
Fix: install uv from https://docs.astral.sh/uv/getting-started/installation/ and re-run /skf-setup. uv is documented as a runtime prerequisite in Getting Started → Prerequisites.
”Setup cannot proceed: _bmad/skf/config.yaml was not found”
Section titled “”Setup cannot proceed: _bmad/skf/config.yaml was not found””Surfaced by /skf-setup On Activation when the SKF install config is missing — typically because you invoked /skf-setup from a directory that is not an SKF-initialised project. The check runs before any file mutation so nothing is written.
Fix: from the project root, run npx bmad-module-skill-forge install (or npx bmad-method install and add SKF as a custom module — see Getting Started → Install), then re-run /skf-setup. If you ARE in the right project but the file was deleted, restore it from version control or re-run the SKF installer. A separate “config.yaml is not valid YAML” diagnostic surfaces the parser error inline if the file exists but is malformed — open the file at the named path and repair the YAML.
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 skill brief found”
Section titled “”No skill brief found””Run @Ferris BS first to create a skill brief, or use @Ferris QS for brief-less generation. CS always requires a brief — either a skill-brief.yaml produced by BS (or AN), or pass the skill name so it resolves one from your forge-data folder. For brief-less generation use QS.
”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.
@Ferris deepwiki shows a deprecation notice
Section titled “@Ferris deepwiki shows a deprecation notice”The auto pipeline was briefly named deepwiki; it’s now forge-auto — renamed to avoid confusion with the DeepWiki MCP, since the pipeline compiles a verified skill from source and does not call that MCP. deepwiki still works (it resolves to forge-auto) but prints a one-time notice. Switch your commands to @Ferris forge-auto <repo-or-doc-url>.
@Ferris onboard returns an error
Section titled “@Ferris onboard returns an error”The onboard alias was removed. Its replacement is forge-auto, which does everything onboard did plus auto-scope, auto-brief, and a stricter 90% quality gate. Run @Ferris forge-auto <repo-or-doc-url> instead.
forge-auto halted at the Test stage
Section titled “forge-auto halted at the Test stage”forge-auto runs Test Skill with a stricter 90% quality threshold (vs the default 80%), so a skill that scores below 90% halts at TS with a gap report rather than exporting a weak skill. Run @Ferris US to address the gaps it lists, then @Ferris TS EX to re-test and export. If 90% is stricter than you need, run the individual workflows or forge instead, which use the default threshold.
My campaign stopped partway — how do I resume?
Section titled “My campaign stopped partway — how do I resume?”Campaign is designed for exactly this. State lives in _campaign-state.yaml on disk, so context death, a session timeout, or a machine restart loses nothing. Run @Ferris campaign resume — Ferris validates the state file, skips completed skills, and picks up from the next incomplete skill in dependency order. If the state file is corrupted, Ferris falls back to the .bak copy automatically. To re-process one specific skill, use @Ferris campaign resume --from=<skill>.
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