Skip to content
Docs: FAQ

Team and help

FAQ and troubleshooting

The questions coworkers ask most, and what to do when something looks wrong.

On this page

Sync says a skill was edited locally

Someone changed a skill's files in the repo after the last sync. Sync will not overwrite their work. Run node .skillify/cli.mjs status to see which skill, then either:

  • Keep the change for everyone: propose it in Skillify (open the skill, Propose a change, paste the edit), or ask your agent to do it with propose_skill_change. Once approved, sync again.
  • Keep it for this repo only: move it into the repo's overlay for that skill, then sync --force.
  • Drop it: node .skillify/cli.mjs sync --force.

Install links last one hour. Open the repo's Install tab again for a fresh one. If the repo is already installed, you do not need a link: run node .skillify/cli.mjs sync with a token.

Sync says it needs a token

Sync reads the library as you. Create a read token in Settings → API tokens, then run node .skillify/cli.mjs login or set SKILLIFY_TOKEN. node .skillify/cli.mjs doctor checks the whole setup.

An agent does not use a skill

Agents choose skills by their description. If a skill is never picked:

  1. Check it is installed: node .skillify/cli.mjs status, and that the agent reads that folder (.claude/skills for Claude Code, .agents/skills for most others).
  2. Read the description as the agent would. It should say when to use the skill, with the words people actually type: “Use when reviewing a pull request”, not “Review utilities”.
  3. Keep it short. Long descriptions blur together; lint warns over 400 characters.
  4. Check usage after a week. If it is still unused, drop it from the repo.

Too many skills, too much context

Every installed skill's description is in every session, used or not. The repo page shows its context cost in tokens. Remove skills nobody uses in that repo, and prefer a few focused skills to many overlapping ones.

AGENTS.md changed in a way I did not expect

Skillify only writes between <!-- skillify:start --> and <!-- skillify:end -->. Anything you write outside the markers stays. Put repo-specific conventions in the repo's notes in Skillify so they live inside the block and stay in sync.

Drift shows “No report”

Nothing has run sync or status in that repo since it was added. Install it, or run node .skillify/cli.mjs status once. Add status --check to CI to keep drift current.

Does Skillify need access to our GitHub?

No. It downloads the skill sources you import, and never reads or writes the repositories you install into. The CLI, run by you, writes files in your checkout.