DEV Community

Pedro Castanheira Costa
Pedro Castanheira Costa

Posted on

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

#ai #claude #productivity #agentskills

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Requires Node ≥ 18.

How a normal feature run feels

  1. You say: “add X / fix Y / refactor Z”
  2. using-project-skills loads domain + stack + conventions
  3. It pulls the module-level skill for the code you’re touching
  4. Work is steered through a spec-driven path (spec → failing tests → implement) when that workflow exists
  5. 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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Which tool combo you use (e.g. Claude + Cursor)
  2. Whether the wizard put files in the right paths
  3. 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).

Top comments (1)

Collapse
 
caioribeiroclw profile image
Caio Ribeiro •

I tried the current repo at 444e75c because the Claude/Cursor combination is exactly the interesting boundary here. The 12/12 suite passes, but I found an adapter-parity gap worth adding to the feedback list:

  • native installs use cpSync(..., { recursive: true }) and preserve the whole skill tree;
  • Cursor/Windsurf adapters read only SKILL.md and emit one flat .mdc/.md file;
  • creating-project-skills and explaining-changes still tell the agent to read/copy references/..., but those files are absent from both adapted installs.

My isolated install produced only creating-project-skills.mdc + explaining-changes.mdc for Cursor (same shape for Windsurf), while both outputs still contained references/ instructions. The current adapter tests actually lock in “single file,” so this survives CI.

Would you prefer copying the support tree beside the converted entry point, or inlining referenced material for rule-only clients? Either way, a useful cross-tool regression would assert that every relative support-file reference resolves after install. Right now “one install, six tools” installs something in all six, but two tools do not receive the same executable skill.