I’ve been building a local AI ops platform and wanted Claude to be able to extend it without ever accidentally touching core files. So I added a .claude/skills/ directory to the repo with a plain Markdown file that gives Claude: the architecture contract (“every feature is a worker, the core is off-limits”) a step-by-step scaffolding workflow (what files to create, in what order, what to confirm before each irreversible step) hard rules that Claude must surface as an explicit contract gap rather than paper over with a silent core edit; and a protocol for what to do if the user tries to override them When anyone opens the repo in Claude Code, the skill loads automatically. Ask “create a new BFrost worker” and Claude follows the full contract without you explaining any of this upfront. It knows the file layout, the storage APIs, the Item Bus contract, the test requirements, the README checklist, all from the skill. The part I found most useful: the skill distinguishes between “things Claude should infer from the docs” and “things Claude needs to ask the user.” It only asks what it can’t figure out from context, so you don’t get bombarded with questions for things the architecture already answers. One more thing worth knowing: the skill is plain Markdown with no Claude-specific syntax. If you use Codex or another assistant, you can drop it into an AGENTS .md at the repo root and it works identically. The pattern is portable. If you’re building something meant to be extended by AI assistants, shipping the architectural contract as a skill seems like a much cleaner approach than hoping contributors read the docs or spending half your review time rolling back core edits that were never supposed to happen. submitted by /u/EmoticonGuess
Originally posted by u/EmoticonGuess on r/ClaudeCode