Features • Contents • Install • Quick Start • Usage • Maintenance
- 🎯 Single source of truth — Keep reusable guidance, formatter defaults, references, and Codex skills in one place.
- 🧭 Agent-ready guidance — Store downstream
AGENTS.mdtemplates and language guides that can be adapted into project-specific instructions. - 🔧 Shared tooling defaults — Version common Oxc, TypeScript, and package script defaults without burying them in individual repos.
- 🔁 Sync workflows — Use bundled skills to merge guidance and config into target projects while preserving local conventions.
- 📚 README polish — Refactor project READMEs into friendly, accurate, emoji-accented documentation.
- 🧪 Migration checks — Audit TypeScript projects for one-time upgrade issues without baking cleanup checklists into downstream guidance.
| Path | Purpose |
|---|---|
configs/ |
Shared config fragments for Oxc, TypeScript path aliases, and package scripts. |
guidance/ |
Reusable downstream agent guidance, language guides, and local overlays. |
references/ |
Structured reference data reused across projects. |
skills/ |
Shareable Codex skills for syncing guidance, project configs, and migration checks. |
docs/ |
Notes, links, and conventions that do not belong in executable configs. |
Clone this repo somewhere stable:
git clone https://github.com/luastoned/code-kit.git
cd code-kitcode-kit is not installed as a project dependency. Its files are copied, merged, or symlinked into local tooling where needed.
The skills/ directory is the source of truth. Each skill is a directory with a SKILL.md entrypoint and YAML frontmatter, which keeps the files portable across agent runtimes that support this shape.
Link the skills from the installed repo path into the runtime you want to use.
test -d "$(pwd)/skills/sync-agent-guidance" && ln -sfn "$(pwd)/skills/sync-agent-guidance" ~/.codex/skills/sync-agent-guidance
test -d "$(pwd)/skills/sync-project-configs" && ln -sfn "$(pwd)/skills/sync-project-configs" ~/.codex/skills/sync-project-configs
test -d "$(pwd)/skills/migrate-typescript" && ln -sfn "$(pwd)/skills/migrate-typescript" ~/.codex/skills/migrate-typescript
test -d "$(pwd)/skills/polish-readme" && ln -sfn "$(pwd)/skills/polish-readme" ~/.codex/skills/polish-readmetest -d "$(pwd)/skills/sync-agent-guidance" && ln -sfn "$(pwd)/skills/sync-agent-guidance" ~/.claude/skills/sync-agent-guidance
test -d "$(pwd)/skills/sync-project-configs" && ln -sfn "$(pwd)/skills/sync-project-configs" ~/.claude/skills/sync-project-configs
test -d "$(pwd)/skills/migrate-typescript" && ln -sfn "$(pwd)/skills/migrate-typescript" ~/.claude/skills/migrate-typescript
test -d "$(pwd)/skills/polish-readme" && ln -sfn "$(pwd)/skills/polish-readme" ~/.claude/skills/polish-readmeRun the commands from the code-kit checkout. The test -d guard ensures the skill exists before linking it, and $(pwd) captures the absolute source path so the agent runtime can resolve the skill directory later.
Claude Code also supports project-local skills under .claude/skills/. For code-kit, the recommended model is to keep this repo as the source of truth and symlink selected skills into the runtime that should consume them.
After linking, start a new agent session so the skills are discovered.
Use $sync-agent-guidance to sync AGENTS.md and mapped language guidance into this project.
Use $sync-project-configs to sync shared config files into this project.
Use $migrate-typescript to audit and migrate this project for TypeScript 6.0+ compatibility.
Use $polish-readme to refresh this project's README.md.
Do not symlink shared config files directly by default. Use the skills to copy or merge configs/, guidance/, and references/ into target projects so local project settings are preserved.
guidance/AGENTS.md is the downstream entrypoint. It maps languages and runtimes to the reusable guides in guidance/.
Private or personal overlays can live under guidance/private/. Files there are ignored by git, so local mappings and non-public guidance stay local.
Use sync-agent-guidance when a project needs local AGENTS.md instructions derived from this repo:
Use $sync-agent-guidance to sync AGENTS.md and mapped language guidance into this project.
The skill inspects the target first, then adapts the reusable guidance instead of copying it blindly.
Use sync-project-configs when a project should receive shared defaults from configs/:
Use $sync-project-configs to sync shared config files into this project.
The skill copies missing relevant configs, merges structured configs where possible, and preserves target-specific settings.
Use migrate-typescript for one-time TypeScript 6.0+ upgrade audits and migration fixes:
Use $migrate-typescript to audit and migrate this project for TypeScript 6.0+ compatibility.
The skill checks deprecated compiler options, deprecated syntax, changed defaults, and project-local typecheck behavior without adding those cleanup steps to downstream AGENTS.md files.
Use polish-readme when a project README should be created, refreshed, or refactored:
Use $polish-readme to refresh this project's README.md.
The skill inspects the target repo first, then rewrites the README around real project contents, commands, links, and examples.
references/gitmojis.json is a structured lookup file for commit tooling and agent workflows that need a local gitmoji reference.
- Keep root
AGENTS.mdfocused on working in this repo. - Keep downstream agent instructions in
guidance/. - Keep private overlays in
guidance/private/; do not publish sensitive or personal project guidance. - Keep reusable tooling defaults in
configs/. - Keep structured lookup data in
references/. - Keep skill workflows concise and procedural in
skills/*/SKILL.md. - Validate JSON after editing config or reference files.