Makes your repo readable to AI agents, then keeps it readable as the code evolves.
One command turns any codebase into structured AI context — CLAUDE.md, project skills, workflow rules — and keeps it accurate automatically as the code changes.
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/klaptorsk/openskulls/main/install.sh | shWindows (PowerShell)
irm https://raw.githubusercontent.com/klaptorsk/openskulls/main/install.ps1 | iexNo Node.js or package manager required — the installer downloads a self-contained binary for your platform directly from GitHub Releases.
Or download manually from the releases page and put the binary anywhere in your PATH.
Re-run the installer — it always pulls the latest release:
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/klaptorsk/openskulls/main/install.sh | sh -s -- --updateWindows (PowerShell)
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/klaptorsk/openskulls/main/install.ps1))) --updateRemove openskulls from a specific repo (git hook, .openskulls/, .claude/, CLAUDE.md):
cd your-project
openskulls uninstallTo keep your manual CLAUDE.md content and only strip the auto-generated sections:
openskulls uninstall --keep-claude-mdRemove the binary from your system:
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/klaptorsk/openskulls/main/uninstall.sh | sh
# Windows — delete the binary directly
Remove-Item "$env:USERPROFILE\.local\bin\openskulls.exe"cd your-project
openskulls initOpenSkulls scans the repo with AI, detects your stack, asks a few workflow questions, shows you a generation plan, then writes:
CLAUDE.md— structured project context for Claude Code.github/copilot-instructions.md— context for GitHub Copilot (if detected).cursor/rules/project.mdc— context rule for Cursor (if detected)AGENTS.md— context for Codex (if detected).claude/skills.md— project-specific AI skills overview.claude/skills/— per-skill reference docs (shared across Claude Code and Copilot).claude/commands/— built-in workflow scripts (run-tests, commit).openskulls/fingerprint.json— baseline for drift detection.openskulls/config.toml— project configuration.git/hooks/post-commit— non-blocking auto-sync hook
Agentic engineering only works when the agent understands the codebase. Right now that understanding has to be built by hand, maintained by hand, and rebuilt whenever the code changes:
- Context rot —
CLAUDE.mdand.cursorrulesgo stale as the codebase evolves, so agents hallucinate based on outdated conventions - Blank-page problem — new teams don't know where to start, so they don't, and agents operate without any structured context at all
- Tool fragmentation — a team using Claude Code + Cursor + Copilot maintains three separate context formats
- Team inconsistency — every developer configures their own context differently, so agents behave differently depending on who set them up
The underlying issue is that context is treated as a document you write, not a property of the codebase you derive. OpenSkulls fixes that.
OpenSkulls runs a single core loop: analyze → generate → maintain.
OpenSkulls scans the local file tree, reads key config files (package.json, tsconfig.json, go.mod, pyproject.toml, etc.), then sends a structured prompt to claude -p via stdin. The AI returns a RepoFingerprint — a rich structured snapshot of everything it detected:
- Languages: every language present, percentage by file count, runtime versions
- Frameworks: frontend, backend, fullstack, ORM, testing — detected from deps and config
- Dependencies: runtime vs. dev, pinned versions, source manifest
- Conventions: linting, formatting, package manager, commit style
- Testing: framework, file patterns, coverage tool
- CI/CD: platform (GitHub Actions, GitLab CI, etc.), deploy targets
- Architecture: style (monolith, monorepo, CLI, microservices), entry points, module structure
- Git: commit style (conventional, jira, freeform), primary branch, contributor count
The fingerprint is stored in .openskulls/fingerprint.json as the baseline for future drift detection. A SHA-256 content hash (excluding machine-specific paths and timestamps) makes it stable and comparable across any machine.
From the fingerprint, OpenSkulls runs a second AI call to generate project skills — repo-specific slash commands tailored to the detected stack. Then the ClaudeCodeGenerator renders all context files.
# repo-name
<!-- openskulls:section:overview -->
## Project Overview
Architecture style, description, primary language and framework.
<!-- /openskulls:section:overview -->
<!-- openskulls:section:tech_stack -->
## Tech Stack
All detected languages (with percentages) and frameworks (with categories).
<!-- /openskulls:section:tech_stack -->
<!-- openskulls:section:architecture -->
## Architecture
Style, API type, database, entry points, module structure.
<!-- /openskulls:section:architecture -->
<!-- openskulls:section:workspace_map -->
## Workspace Map
Table of discovered sub-workspaces with language/framework summary. Only present in monorepos.
<!-- /openskulls:section:workspace_map -->
<!-- openskulls:section:conventions -->
## Conventions
Detected conventions: package manager, TypeScript config, linting tools.
<!-- /openskulls:section:conventions -->
<!-- openskulls:section:testing -->
## Testing
Framework, test file pattern, coverage tool.
<!-- /openskulls:section:testing -->
<!-- openskulls:section:cicd -->
## CI/CD
Platform and deploy targets (only when detected).
<!-- /openskulls:section:cicd -->
<!-- openskulls:section:workflow_rules -->
## Workflow Rules
Auto-documentation and auto-commit policies (from your init answers).
<!-- /openskulls:section:workflow_rules -->
<!-- openskulls:section:architect_guardrails -->
## Architectural Guardrails
Module ownership, layer rules, placement rules, and forbidden patterns. Generated for complex or monorepo projects.
<!-- /openskulls:section:architect_guardrails -->
<!-- openskulls:section:agent_guidance -->
## Agent Guidance
Commit format, working patterns, scope constraints.
<!-- /openskulls:section:agent_guidance -->
---
## Key Files ← your manual section — never touched by openskulls
| Path | Purpose |
| ---- | ------- |Tagged sections (<!-- openskulls:section:* -->) are owned by OpenSkulls and regenerated on sync. Everything outside those tags is yours — preserved permanently, including manual sections you add below.
The second AI call generates project-specific skills: slash commands with rich reference content tailored to your stack. Each skill lives at .claude/skills/<id>/SKILL.md with YAML frontmatter that registers it as a /<id> slash command in Claude Code.
.claude/
├── skills.md # overview of all AI-generated skills, grouped by category
└── skills/
├── add-api-endpoint/
│ └── SKILL.md # /add-api-endpoint
├── write-unit-test/
│ └── SKILL.md # /write-unit-test
└── run-migration/
└── SKILL.md # /run-migration
Skills are non-fatal: if the AI call fails, init and sync continue without them.
When GitHub Copilot is an enabled target, AI-generated skills are emitted to .claude/skills/<id>/SKILL.md — the same path and format used by Claude Code. Built-in skills (run-tests, commit) go to .claude/commands/ and pack skills are emitted identically. This means one set of skill files works for both tools.
Built-in workflow scripts are emitted automatically when conditions are met:
| File | Condition |
|---|---|
run-tests.md |
Testing framework detected (/run-tests) |
commit.md |
Conventional Commits style detected (/commit) |
Skills from installed packs (via openskulls add) are emitted as .claude/skills/<pack>-<id>/SKILL.md alongside the AI-generated skills. They appear as slash commands in Claude Code just like any other skill.
A non-blocking post-commit hook watches for drift. When dependencies change, frameworks are added, or architecture shifts — OpenSkulls detects the delta and updates context automatically. The hook never blocks a commit and never interrupts developer flow.
Analyse a repository and generate AI context files. Runs the full pipeline.
openskulls init # current directory
openskulls init ./my-service # explicit path
openskulls init --dry-run # preview without writing
openskulls init --yes # skip confirmation prompts
openskulls init --verbose # show AI prompts and raw responsesInit flow:
- Analyse repo — scans file tree, reads config files, invokes
claude -pfor AI analysis- 1a. Discover workspaces — auto-scans for sub-repos (packages, services, apps); shown as a table if found
- 1b. Scan foreign files — detects existing AI instruction files not managed by openskulls (CLAUDE.md, AGENTS.md, copilot-instructions.md, etc.)
- 1c. AI import foreign files — extracts conventions, rules, and constraints from existing files and folds them into the fingerprint (non-fatal)
- Show detected signals — languages, frameworks, testing, linting in a table
- Generate contextual questions — AI call produces repo-specific questions based on the fingerprint (non-fatal, skipped with
--yes) - Workflow setup — static questions + AI-generated contextual questions to configure how Claude works in this repo (skipped with
--yes) - Generate project skills — AI call produces repo-specific slash commands, using your answers as context (non-fatal)
- Generate architect skill — optional AI call that generates a domain-expert architect agent (if enabled in step 4)
- Generate methodology skills — AI call produces architect, workflow-lifecycle, verify, and tdd skills grounded in the actual project structure (non-fatal)
- Generate architectural guardrails — AI call produces inline module-ownership rules and placement constraints for complex or monorepo projects (non-fatal)
- Generate files — renders
CLAUDE.mdand all context files from the fingerprint; in a monorepo, per-workspace files are generated first then the root aggregate - Show generation plan — lists every file that will be created or updated
- Confirm — nothing is written until you approve (skipped with
--yes) - Write files — applies merge strategy per file (see Merge Strategy)
- Save baseline — writes
.openskulls/fingerprint.json,.openskulls/config.toml, and per-workspace.openskulls/fingerprint.jsonfiles - Install git hook — adds
.git/hooks/post-commitfor automatic drift detection
Verbose mode (--verbose / -v): prints the full AI prompt and raw JSON response for every AI call — analysis, questionnaire, skills, and architect. Useful for debugging or understanding what was sent to the model.
Diagnostic log: if analysis fails, a .openskulls/last-error.log is written with the full prompt, raw AI response, and error details — no --verbose flag needed for post-mortem debugging.
Workflow questions (step 4):
All prompts use interactive arrow-key selectors — use ↑/↓ to navigate, Space to toggle (multi-select), Enter to confirm. Cancel any prompt with Ctrl+C.
| Question | Options | Default |
|---|---|---|
| AI tool (output format) | Claude Code, GitHub Copilot, OpenAI Codex, Cursor | Claude Code |
| Auto-documentation | Ask me first / Update automatically / Handle myself | Ask me first |
| Auto-commit | Ask me first / Commit automatically / Never | Ask me first |
| Architect agent | Yes / No | Yes |
| (If yes) Architect domain | Auto-detect / Backend / Frontend / Full-stack / Data-ML / DevOps / Mobile / Other (custom) / Skip | Auto-detect |
| Architect review trigger | Ask me first / Always / Only on /architect-review |
Ask me first |
| Skill generation | Single AI call / Parallel subagents | Single AI call |
Answers are saved to .openskulls/config.toml and generate a workflow_rules section in CLAUDE.md that instructs Claude on your preferences.
When you choose parallel subagents in the workflow setup, the skills AI call and the architect AI call run simultaneously via Promise.allSettled instead of sequentially. This cuts generation time roughly in half when both are enabled, at the cost of two concurrent AI sessions instead of one.
Both calls are non-fatal — if either fails the other still completes and init continues. The setting is saved as use_subagents = true in .openskulls/config.toml.
When enabled, openskulls init (and openskulls sync) runs a third AI call to generate a /architect-review slash command tailored to your codebase. The agent acts as a domain-expert reviewer, producing:
- Architectural Principles — non-negotiable rules specific to your stack
- Review Checklist — 6–10 items to verify on every feature or change
- Anti-Patterns — stack-specific patterns to flag in code review
- Common Patterns — canonical patterns referencing real paths in your repo
The prompt template lives at templates/prompts/architect.md.hbs and can be edited directly to tune output without touching TypeScript.
When architect_review = "always" is set in config, the generated skill includes a Workflow section that instructs Claude to run /architect-review as a required step after every feature addition.
Update context files to match the current state of the repo. Run this after pulling changes from teammates, or when the post-commit hook reports drift.
openskulls sync # show diff and confirm before writing
openskulls sync --dry-run # show what would change
openskulls sync --yes # apply without confirmationSync detects drift by comparing the current repo's contentHash against the stored baseline. If the hash changed, it runs the full analysis → generate pipeline and shows exactly which sections would be updated before writing anything.
Workflow config is read from .openskulls/config.toml — if the architect agent was enabled during init, sync regenerates the /architect-review skill automatically.
Hook mode (called automatically by the post-commit hook):
openskulls sync --hook --changed "package.json\nsrc/server.ts"In hook mode, OpenSkulls checks whether any changed file matches a trigger pattern. If no trigger file changed it exits immediately (fast path). All output is suppressed. The process always exits 0 — a sync failure never blocks a commit.
Default trigger patterns:
package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb
requirements*.txt, pyproject.toml, Pipfile, Pipfile.lock
go.mod, go.sum
Cargo.toml, Cargo.lock
Gemfile, Gemfile.lock
tsconfig*.json
.github/workflows/**
Check the health of the current context against the repo. Produces a report showing:
- Stale references — packages or frameworks in context that are no longer in the dependency graph
- Missing coverage — major modules or patterns not represented in context
- Drift score — how far the current repo has moved from the fingerprint baseline
openskulls audit # interactive report
openskulls audit --ci # exit non-zero if drift exceeds threshold (CI gate)
openskulls audit --json # machine-readable outputInstall a skill pack from GitHub or a local path. No registry required — packs are plain git repos with a skull-pack.toml manifest.
openskulls add github:user/react-patterns
openskulls add github:user/react-patterns#v1.0.0 # pin to a tag
openskulls add ../local/my-company-pack # local symlinkThe pack is cloned into .openskulls/packs/ (gitignored), the manifest is validated, and the source URL is recorded in .openskulls/config.toml. Run openskulls sync after adding to regenerate context files with the new pack's skills.
Remove an installed skill pack.
openskulls remove react-patternsRemoves the pack directory and its config entry. Run openskulls sync to regenerate context without the pack.
Show all installed skill packs.
openskulls listDisplays pack name, source URL, skill count, and rule count.
Remove all openskulls-generated files from a repository.
openskulls uninstall # shows plan then confirms
openskulls uninstall --keep-claude-md # strip managed sections, preserve manual content
openskulls uninstall --yes # skip confirmationRemoves: post-commit hook, .openskulls/, .claude/, and CLAUDE.md (or just its managed sections with --keep-claude-md). Does not remove the global binary — use the uninstall script for that.
OpenSkulls never blindly overwrites files. Each generated file has a declared merge strategy:
| Strategy | Used for | Behaviour |
|---|---|---|
merge_sections |
CLAUDE.md, .claude/skills.md |
Regenerates only <!-- openskulls:section:* --> blocks; all manual content is preserved in place |
replace |
.claude/settings.json, skill files |
Overwrites the entire file |
The section merge algorithm (src/core/generators/merge.ts) is a pure function with no I/O:
- Parse the existing file into alternating manual and managed chunks
- Build a map of new managed section content
- Rebuild: preserve manual chunks in order, replace managed sections with new versions, append any new sections
The result: multiple syncs are safe, manual edits survive, and no content is ever silently lost.
Context is not one thing. OpenSkulls enforces a clear separation between what belongs to the developer and what belongs to the project:
~/.claude/CLAUDE.md # Your identity: name, preferences, style
~/.claude/commands/ # Personal skills: carried across every repo
[repo]/.openskulls/config.toml # OpenSkulls project config (committed)
[repo]/.openskulls/fingerprint.json # Drift baseline (committed)
[repo]/CLAUDE.md # Project context (committed)
[repo]/.claude/skills.md # AI-generated skills overview (committed)
[repo]/.claude/skills/ # AI-generated per-skill docs (shared: Claude Code + Copilot)
[repo]/.claude/commands/ # Built-in and package workflow scripts (committed)
[repo]/.claude/settings.json # Claude Code settings (committed)
Personal context (~/.claude/) is never committed. It follows you across every repo.
Project context ([repo]/) is committed. Every teammate gets the same baseline after pulling.
Team consistency emerges naturally: when .openskulls/config.toml and CLAUDE.md are committed, every developer who pulls and runs openskulls sync gets the current project context.
Project configuration lives in .openskulls/config.toml (committed to the repo):
schema_version = "1.0.0"
[[targets]]
name = "claude_code"
enabled = true
[[targets]]
name = "cursor"
enabled = true
[workflow]
auto_docs = "ask" # "always" | "ask" | "never"
auto_commit = "ask" # "always" | "ask" | "never"
architect_enabled = true
architect_domain = "" # leave blank to auto-detect
architect_review = "ask" # "always" | "ask" | "never"
use_subagents = false # true = run skills + architect in parallel
exclude_paths = [
"node_modules", ".git", "dist", "build",
".venv", "__pycache__", ".next", ".nuxt", "coverage"
]
# Monorepo workspace config (written automatically on init if workspaces discovered)
[workspaces]
manual = false # true = only use declared [[workspaces.entries]]
max_depth = 3
exclude_patterns = ["node_modules", "dist", ".git"]
# [[workspaces.entries]]
# path = "packages/api"
# name = "API Service"
# targets = ["claude_code"]workflow.auto_docs and workflow.auto_commit are set during openskulls init and drive the ## Workflow Rules section in CLAUDE.md. They can be changed by editing the file and re-running openskulls sync.
Personal global config lives in ~/.openskulls/config.json (never committed):
{
"schemaVersion": "1.0.0",
"preferredTools": ["claude_code"],
"developerProfile": {
"name": "",
"preferredEditor": "",
"codingStyleNotes": "",
"personalRules": []
}
}After openskulls init, the fingerprint is committed to .openskulls/fingerprint.json. Each file in the fingerprint contributes to a SHA-256 contentHash (excluding repoRoot, generatedAt, and contentHash itself), so the hash is machine-independent — the same codebase produces the same hash anywhere.
The post-commit hook runs openskulls sync --hook after every commit. If a trigger-pattern file changed, it re-fingerprints the repo and compares hashes. On drift, it updates context files silently. On failure, it exits 0.
Drift categories:
| Category | Example trigger |
|---|---|
| Dependency drift | New package added, major version bump |
| Framework drift | New framework detected in dependency graph |
| Convention drift | New linter config, formatter config changed |
| Architecture drift | New module boundary, tsconfig.json path change |
| CI/CD drift | New workflow file added under .github/workflows/ |
The analysis pipeline (src/core/fingerprint/ai-collector.ts) uses Claude Code's claude -p subprocess via stdin — no hardcoded language parsers, no regex matching against a fixed list.
Pipeline:
- Walk repo file tree (max depth 6), cataloguing ~50 known config file types
- Read key config file contents (up to 32 KB each)
- Detect installed AI CLI tools (by checking
$PATHdirs for execute permission) - Build a structured analysis prompt from the file tree and config contents
- Pipe prompt to
claude -pvia stdin (avoidsARG_MAXlimits) - Parse and Zod-validate the JSON response
- Compute
contentHashand assemble theRepoFingerprint
Because analysis is AI-driven, OpenSkulls can detect any language, framework, or convention — not just the ones on a hardcoded list. The output is always validated against a Zod schema before use.
Because analysis is AI-powered, OpenSkulls can detect any stack. The following are reliably detected because their config files are always read:
| Language | Version source |
|---|---|
| Python | pyproject.toml, .python-version |
| JavaScript | package.json engines field |
| TypeScript | package.json typescript dep |
| Go | go.mod |
| Rust | Cargo.toml |
| Ruby | Gemfile, .ruby-version |
| Category | Frameworks |
|---|---|
| Full-stack | Next.js, Nuxt, Remix, SvelteKit |
| Frontend | React, Vue, Svelte, SolidJS, Angular |
| Backend (JS/TS) | Express, Fastify, Koa, Hono, NestJS, tRPC, GraphQL |
| Backend (Python) | FastAPI, Django, Flask, Starlette, Litestar, aiohttp |
| Backend (Go) | Gin, Echo, Fiber, Gorilla Mux, Chi, gRPC |
| ORM (JS/TS) | Prisma, Drizzle, Mongoose, TypeORM |
| ORM (Python) | SQLAlchemy, Tortoise ORM |
| ORM (Go) | GORM, sqlx, Bun, Ent |
| ML / Data | PyTorch, TensorFlow, HuggingFace Transformers, NumPy, Pandas |
| CLI | Cobra, Click, Typer, urfave/cli, Commander |
| Validation | Zod, Pydantic |
| Desktop | Electron, Tauri |
| Language | Frameworks |
|---|---|
| JavaScript/TypeScript | Vitest, Jest, Mocha, Playwright, Cypress |
| Python | pytest, unittest |
| Go | built-in testing, testify |
| Language | Tools |
|---|---|
| JavaScript/TypeScript | ESLint, Prettier, Biome, XO |
| Python | Ruff, mypy, Black, pylint, isort, flake8 |
| Go | golangci-lint, gofmt |
git clone https://github.com/klaptorsk/openskulls
cd openskulls
bun install
bun run compile # produces ./openskulls binary
./openskulls --versionOr build a development dist and link it globally:
bun run build
bun link # makes `openskulls` available globallyRun the test suite:
bun run test- Generators are pure functions —
generate(input): GeneratedFile[]never writes to disk. The CLI layer owns all I/O. This enables dry-run, diff preview, and CI mode. - Zod as source of truth — all types are
z.infer<typeof Schema>. The same schemas validate AI responses at runtime and provide compile-time safety. - Analysis engine ≠ output target — the user's tool selection (Claude Code, Copilot, Cursor, Codex) determines which output files are generated. The analysis engine is detected separately, always preferring the best available CLI (
claude>codex>copilot). A Copilot user with Claude Code installed gets Claude's analysis quality while still generatingcopilot-instructions.md. On Windows, prompts are delivered via PowerShellStart-Process -RedirectStandardInput(native file handle) to bypass.cmdwrapper stdin issues. - Content-addressed fingerprints — SHA-256 over content fields only (no paths, no timestamps). Same codebase = same hash on any machine, in any directory.
- Non-blocking hooks — the post-commit hook always exits 0. A sync failure or analysis error never interrupts a developer's commit.
For full module structure, data flow diagrams, config file schemas, and an extension guide, see docs/ARCHITECTURE.md.
| Version | Focus |
|---|---|
| v0.1 | Core loop: init, sync — AI-powered analysis — Claude Code, Cursor, Copilot, Codex generators — workflow rules — parallel skill generation — git hook |
| v0.2 | Git-native skill packs (add, remove, list) — AI methodology skills (architect, workflow-lifecycle, verify, tdd) — pack skill emission |
| v0.3 | Architectural guardrails — Monorepo / multi-workspace support — Foreign file inheritance |
| v0.4 | Shared skill files across generators — Copilot uses .claude/skills/ for interoperability |
| v0.5 | openskulls audit — openskulls sync --watch — pack auto-update on sync |
| v1.0 | Platform: org-level context — agent performance metrics — multi-agent profiles |
MIT