Stop re-explaining your codebase to every AI agent — `cast-skills`

Pedro Castanheira Costa — Wed, 15 Jul 2026 01:12:25 +0000

The annoying part of AI coding tools

Every session, the agent forgets:

your module boundaries
the “every user belongs to an org” rule that lives in nobody’s file
which service emits which event
how you want features built (tests first? spec first? conventions?)

So you re-explain. It rewrites. Context drifts. Tokens burn.

Dumping a 40k-token AGENTS.md into every prompt is not a strategy. It’s a tax.

I wanted something simpler: write project knowledge once, in a format agents already understand, and install it into every tool I actually use.

That’s cast-skills.

npx cast-skills

What it is

cast-skills is a small CLI that bootstraps cross-tool AI skills for your machine (or project):

Skill	Job
`using-project-skills`	Always-on router. When you start a feature/fix/refactor, it loads project context and routes work through the right module + workflow.
`creating-project-skills`	Bootstrapper (`/skill-creator`). Reads the repo, asks sharp questions, generates a project skill tree.
`explaining-changes`	After non-trivial work, offers a beginner-friendly explanation (ELI5 → runtime) as Markdown/HTML.

Skills use the open SKILL.md format — progressive disclosure: the agent loads what it needs, not your entire wiki every turn.

cast-skills is built around Anthropic's Agent Skills approach: instead of loading one massive prompt every session, the agent progressively loads only the knowledge it needs.

One install. Six tools.

The wizard auto-detects what you have and drops skills in the right place:

Tool	Where it goes	Format
Claude Code	`~/.claude/skills/`	native `SKILL.md`
GitHub Copilot	`~/.copilot/skills/`	native
Gemini CLI	`~/.gemini/skills/`	native
Codex	`~/.agents/skills/`	native
Cursor	`.cursor/skills/` (project)	converted `.mdc`
Windsurf	`.windsurf/rules/` (project)	converted rules

Native tools get SKILL.md as-is. Cursor/Windsurf get an auto-converted format so you’re not maintaining six copies by hand.

npx cast-skills
# or
npm i -g cast-skills && cast-skills

Requires Node ≥ 18.

How a normal feature run feels

You say: “add X / fix Y / refactor Z”
using-project-skills loads domain + stack + conventions
It pulls the module-level skill for the code you’re touching
Work is steered through a spec-driven path (spec → failing tests → implement) when that workflow exists
After a real change, explaining-changes can leave a human-readable write-up

The point isn’t another chatbot persona. It’s stable project memory that survives sessions and tools.

Why I didn’t make this Claude-only

Most of us don’t live in one harness.

Monday: Claude Code.

Tuesday: Cursor on a design-heavy UI.

Wednesday: Copilot in a boring enterprise repo.

If “project brain” only works in one tool, you still re-explain on Tuesday.

cast-skills optimizes for write once → run everywhere that speaks skills/rules.

What this is not

Not a full coding agent (that’s a different product surface)
Not magic RAG over your monorepo (skills are curated knowledge, not automatic embeddings)
Not a replacement for good architecture — garbage conventions in → garbage guidance out

If your team has no conventions, the bootstrapper will still force a few useful questions. That’s a feature.

Try it in 30 seconds

cd your-repo
npx cast-skills

Pick the tools you use → let it install the three skills → start a real task and see if the agent stops inventing your architecture from scratch.

Repo: github.com/pedrocastanha/cast-skills

npm: npmjs.com/package/cast-skills

Feedback I actually want

If you try it, tell me:

Which tool combo you use (e.g. Claude + Cursor)
Whether the wizard put files in the right paths
One rule your team has that should be a skill but isn’t obvious

Issues and PRs welcome — especially path fixes for tool updates (these CLIs move the goalposts often).

DEV Community: Pedro Castanheira Costa