AI Initializer

AI Initializer is a project that makes your projects AI-ready — delivered as a reusable agent skill you install into any codebase.

It scaffolds a dual-entry-point AI configuration: thin AGENTS.md (opencode) and CLAUDE.md (Claude Code) point to shared knowledge in .ai/. Claude Code, opencode, and Cursor read the same content — zero duplication, one place to edit per topic.

AI Initializer 是一个让项目 AI 化的项目，以可复用 skill 的形式安装到任意代码库。AGENTS.md 和 CLAUDE.md 是薄入口，项目知识放在 .ai/ 目录；Claude Code、opencode 和 Cursor 读同一份内容，零重复，一处维护。

---

Install

The skill is distributed through npx skills — GitHub is the registry, no npm publish needed:

npx skills add YoungLee-coder/AI-Initializer

This installs the skill into .claude/skills/ai-initializer/ (or your agent's skills dir). Add -g for a global (user-level) install:

npx skills add YoungLee-coder/AI-Initializer -g

通过 npx skills add 安装，GitHub 即注册表，无需发布 npm 包。-g 装到用户级，全局可用。

Use

In the project you want to configure, ask your agent:

初始化AI配置        # or: set up AGENTS.md / scaffold AI config / init agents config

The skill then:

1. Analyzes the codebase — language, build/test/lint/format commands, directory layout, test framework, installed formatters, safety surfaces, response language.
2. Asks which AI tools you use — including whether to add optional Cursor configuration (.cursor/rules/).
3. Drafts .ai/ content — 6 focused files (project, architecture, coding-style, workflow, testing, security) — and shows them to you to confirm/edit.
4. Writes entry points — thin AGENTS.md + CLAUDE.md (both point to .ai/) + opencode.jsonc (with instructions field) + .gitignore block.
5. Adds .claude/ automation — block-dangerous hook, post-edit-check hook, 3 subagents, 4 starter skills (including remember), settings-example.json (rename to settings.json to activate).
6. Adds .cursor/ adapters (if you use Cursor) — project-context.mdc rule only.
7. Verifies & summarizes what it created.

Existing AI config is backed up to .ai-init-backup/, never silently overwritten.

What it generates

AGENTS.md                      # thin entry for opencode (tracked)
CLAUDE.md                      # thin entry for Claude Code (tracked, real file)
opencode.jsonc                  # opencode config: instructions → .ai/ files (tracked)
.ai/                            # shared project knowledge (tracked)
  project.md                    # project background, response language
  architecture.md                # repository map, hotspot ownership
  coding-style.md                # conventions, helpers, gotchas
  workflow.md                    # commands, verification, release flow
  testing.md                    # test strategy, per-change verification
  security.md                    # safety rules (optional — only if applicable)
.gitignore                     # + block: *.local.md, settings.local.json, .opencode/
.claude/
  settings-example.json      # hook config (rename to settings.json to activate)
  hooks/block-dangerous.sh      # blocks rm -rf /, force push, DROP TABLE, etc.
  hooks/post-edit-check.sh      # formats + lightweight lint/typecheck after edits
  agents/code-reviewer.md      # project-tailored review subagent
  agents/security-auditor.md   # security audit subagent (optional)
  agents/architect.md          # architectural review subagent
  skills/{{PROJECT_SLUG}}-implement-feature/     # feature implementation workflow (starter)
  skills/{{PROJECT_SLUG}}-review-pr/             # PR review workflow (starter)
  skills/{{PROJECT_SLUG}}-release-check/         # release readiness workflow (starter)
  skills/{{PROJECT_SLUG}}-remember/            # add persistent memory to .ai/
.cursor/                        # optional — if you use Cursor
  rules/project-context.mdc     # alwaysApply thin pointer to .ai/

How it works

Component	What it does
AGENTS.md	Thin opencode entry: version marker + defers .ai/ index to CLAUDE.md
CLAUDE.md	Canonical .ai/ file index + Claude-specific notes (also auto-loaded by Cursor)
opencode.jsonc	instructions field explicitly loads .ai/ files into context
.ai/ files	The real knowledge — project, architecture, conventions, commands, tests, security
.cursor/rules/	Optional: alwaysApply rule reinforcing .ai/ reads (Cursor Agent only)
.claude/skills/	Project workflows + remember for adding facts to .ai/ — discovered by Claude Code and Cursor
block-dangerous.sh	PreToolUse hook: blocks catastrophic commands before execution
post-edit-check.sh	PostToolUse hook: formats file + runs lightweight checks after edits
Subagents	Read-only auditors tailored to this repo's specific recurring mistakes

Why this shape

See skills/ai-initializer/references/architecture.md for the full rationale. The short version:

• Two thin entries beat a symlink. CLAUDE.md is a real file (not a symlink) — more robust, can contain Claude-specific notes.
• Shared .ai/ beats a monolithic file. Focused files are easy to scan, easy to edit independently, fewer merge conflicts.
• opencode.jsonc instructions is native. Guaranteed loading mechanism, not a hope that the agent reads a file list.
• Cursor is optional. Cursor auto-loads AGENTS.md + CLAUDE.md; add .cursor/rules/ only when you want stronger .ai/ integration. Workflows live in .claude/skills/.
• Persistent memory. Use /{{PROJECT_SLUG}}-remember to add facts to .ai/; agents propose saving stable conventions with your confirmation.
• One knowledge source per topic. If updating a build command means touching two files, the architecture is broken.

Repository layout

skills/ai-initializer/
  SKILL.md                     # the 6-phase workflow the agent follows
  references/                  # architecture, .ai/ guide, cursor adapters, settings merge, version changelog
    migration-policy.md        # upgrade window; incremental vs full re-scaffold
    migrations/                # v{N}-to-v{N+1}.md (recent window only) + full-rescaffold.md
  templates/                   # entry points, .ai/ skeletons, opencode.jsonc, .claude + .cursor config

Credit

The architecture was originally inspired by tw93/Mole. Packaging follows vercel-labs/skills.