Skills management

[daviddflix]

I'm currently using the .pi/skills directory to store the skills I want my agents to have. However, sometimes it works and sometimes it doesn't. Am I doing something wrong?

[VectorPeak]

.pi/skills is project-scoped, not global. It only gets picked up for the project that owns that directory, and project-local skills require the project to be trusted. That’s the most common reason it feels inconsistent: an interactive run may prompt/remember trust, while a background or non-interactive run may skip project-local resources if there isn’t already a trust decision.

For skills you want available across all projects, use:

~/.pi/agent/skills/

For repo-specific skills, .pi/skills is fine, but make sure Fusion is running with that repo as the project/cwd and that the project has been trusted.

Also check the skill shape. The reliable layout is:

.pi/skills/my-skill/SKILL.md

with required frontmatter:

---
name: my-skill
description: Use this when ...
---

A missing description will prevent the skill from loading. Duplicate name values can also make it look random, because the first discovered skill wins and the later one is ignored with a warning.

---

If my answer solved your problem, you can click answered the question. I'm really here to help, and along the way I'm also collecting Galaxy Brain badges haha 😆