{"id":50791393,"url":"https://github.com/vpxuser/claude-code-devkit","last_synced_at":"2026-06-12T11:30:19.631Z","repository":{"id":363517257,"uuid":"1263134712","full_name":"vpxuser/claude-code-devkit","owner":"vpxuser","description":"The missing style guide for Claude Code — templates, rules, reviewers, scaffolding","archived":false,"fork":false,"pushed_at":"2026-06-09T07:47:44.000Z","size":72,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T09:24:56.267Z","etag":null,"topics":["ai-coding","anthropic","claude","claude-code","code-style","developer-tools","linting","scaffolding","templates"],"latest_commit_sha":null,"homepage":"https://docs.anthropic.com/en/docs/claude-code","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vpxuser.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T16:51:42.000Z","updated_at":"2026-06-09T07:47:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vpxuser/claude-code-devkit","commit_stats":null,"previous_names":["vpxuser/claude-code-devkit"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/vpxuser/claude-code-devkit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpxuser%2Fclaude-code-devkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpxuser%2Fclaude-code-devkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpxuser%2Fclaude-code-devkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpxuser%2Fclaude-code-devkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vpxuser","download_url":"https://codeload.github.com/vpxuser/claude-code-devkit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vpxuser%2Fclaude-code-devkit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34243051,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","anthropic","claude","claude-code","code-style","developer-tools","linting","scaffolding","templates"],"created_at":"2026-06-12T11:30:16.595Z","updated_at":"2026-06-12T11:30:19.626Z","avatar_url":"https://github.com/vpxuser.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Code DevKit\n\n**A blueprint project that guides Claude Code to generate correct Claude Code configuration files following official design philosophy.**\n\nThis project serves as a living reference — it contains templates, guides, and a core design philosophy skill that Claude Code uses to generate files like `SKILL.md`, `Agent.md`, `.mcp.json`, `hooks.json`, `settings.json`, `plugin.json`, `commands/*.md`, and `CLAUDE.md`.\n\n## How it works\n\nClaude Code reads the project's `.claude/CLAUDE.md` and `.claude/skills/claude-code-design-philosophy/SKILL.md` at startup. These files teach Claude Code the official design patterns for every file type it might need to generate. Template files in `templates/` serve as starting points, and guides in `guides/` provide detailed generation rules.\n\n## File types covered\n\n| File | Purpose | Official docs |\n|------|---------|---------------|\n| `SKILL.md` | Modular capabilities with progressive disclosure | [Skills Overview](https://docs.anthropic.com/en/docs/claude-code/skills) |\n| `Agent.md` | Autonomous subprocess definitions | [Agents](https://docs.anthropic.com/en/docs/claude-code/agent) |\n| `.mcp.json` | MCP server configuration | [MCP](https://code.claude.com/docs/en/mcp) |\n| `hooks.json` | Event-driven automation hooks | [Hooks](https://code.claude.com/docs/en/hooks) |\n| `settings.json` | Claude Code project/user settings | [Configuration](https://code.claude.com/docs/en/configuration) |\n| `plugin.json` | Plugin manifest | [Plugins](https://code.claude.com/docs/en/plugins) |\n| `commands/*.md` | Slash command definitions | Commands (in plugins guide) |\n| `CLAUDE.md` | Project-level instructions | [Overview](https://docs.anthropic.com/en/docs/claude-code/overview) |\n| `.local.md` | Plugin settings/state files | Plugin settings pattern |\n\n## Quick start\n\nTo use this devkit, start a Claude Code session in this directory. Claude Code will automatically load the design philosophy skill and project instructions. Then ask:\n\n- \"Generate a SKILL.md for a PDF processing skill\"\n- \"Create an Agent.md for a code reviewer\"\n- \"Set up .mcp.json to connect to PostgreSQL\"\n- \"Create a plugin for database migrations\"\n\nOr use the built-in command:\n```\n/generate-file \u003ctype\u003e [description]\n```\n\n## Project structure\n\n```\nclaude-code-devkit/\n├── .claude/\n│   ├── CLAUDE.md              # Project instructions for Claude Code\n│   ├── settings.json          # Permissions, hooks config + auto-validation\n│   ├── settings.local.json    # Local overrides (not in git)\n│   ├── scripts/\n│   │   └── validate.sh        # Post-write validation engine for all file types\n│   ├── skills/\n│   │   └── claude-code-design-philosophy/\n│   │       └── SKILL.md       # Core design philosophy skill\n│   └── commands/\n│       ├── generate-file.md   # /generate-file — scaffold any config file\n│       └── validate.md        # /validate — manually validate all files\n├── guides/\n│   ├── design-philosophy.md   # Core design philosophy reference\n│   ├── skill-guide.md         # SKILL.md generation rules\n│   ├── agent-guide.md         # Agent.md generation rules\n│   ├── mcp-guide.md           # .mcp.json generation rules\n│   ├── hooks-guide.md         # hooks.json generation rules\n│   ├── command-guide.md       # Command file generation rules\n│   ├── settings-guide.md      # settings.json generation rules\n│   ├── plugin-guide.md        # Plugin generation rules\n│   └── claude-md-guide.md     # CLAUDE.md generation rules\n├── templates/\n│   ├── SKILL.md               # SKILL.md template\n│   ├── AGENT.md               # Agent.md template\n│   ├── mcp.json               # MCP config template\n│   ├── hooks.json             # Hooks config template\n│   ├── plugin.json            # Plugin manifest template\n│   ├── settings.json          # Settings config template\n│   ├── command.md             # Command file template\n│   └── CLAUDE.md              # CLAUDE.md template\n└── README.md                  # This file\n```\n\n## Design philosophy\n\nClaude Code configuration files follow these core principles:\n\n1. **Progressive disclosure** — Only load what's needed, when it's needed\n2. **Conciseness** — Claude is already smart; only add context it doesn't have\n3. **Filesystem-based** — Files exist on disk, Claude reads/executes them via bash\n4. **YAML frontmatter** — Metadata in frontmatter, instructions in the body\n5. **Third-person descriptions** — Descriptions are injected into the system prompt\n6. **Kebab-case naming** — Lowercase letters, numbers, and hyphens only\n\nSee `guides/design-philosophy.md` and the core skill for full details.\n\n## Auto-Validation\n\nWhen you write or edit a Claude Code configuration file in this project, a `PostToolUse` hook automatically runs the validation script (`.claude/scripts/validate.sh`). It checks:\n\n| Check | What it validates |\n|-------|-------------------|\n| **SKILL.md** | YAML frontmatter, kebab-case name, no reserved words, description rules, body non-empty, **body writing style (imperative, concise, no anti-patterns)**, body under 500 lines |\n| **Agent.md** | Name length (3-50), `\u003cexample\u003e` blocks with `\u003ccommentary\u003e`, `model` and `color` fields |\n| **.mcp.json** | Valid JSON, server type consistency, required fields per type (stdio/HTTP/SSE) |\n| **hooks.json** | Valid JSON, valid event names, non-empty hook configurations |\n| **plugin.json** | Valid JSON, required `name` field, kebab-case name |\n| **settings.json** | Valid JSON, recognized top-level keys |\n| **commands/*.md** | Writing style (must be TO Claude, not TO user), frontmatter |\n| **CLAUDE.md** | Non-empty content, specific title |\n\nValidation results appear in the Claude Code transcript. Use `/validate` to manually validate all files at once.\n\n## Deploy to Other Projects\n\n### Option 1: Deployment script (recommended)\n\n```bash\n# From the devkit directory:\nbash deploy.sh /path/to/target-project          # Validation only\nbash deploy.sh /path/to/target-project --full   # Full: validation + skill + commands\nbash deploy.sh /path/to/target-project --dry-run  # Preview only\n```\n\nThis copies the validation script, commands, and hooks into the target project's `.claude/` directory. The `--full` mode also installs the design philosophy skill, guides, and templates.\n\n### Option 2: Plug and play (plugin install)\n\nUse the devkit as a Claude Code Plugin for ad-hoc access to validation in any project:\n\n```bash\n# From a project where you want devkit features:\nclaude --plugin-dir /path/to/claude-code-devkit\n```\n\nThis grants temporary access to all devkit commands (`/validate`, `/generate-file`) and the validation hook without installing into the project permanently.\n\n### Option 3: Manual install\n\nCopy only what you need:\n\n| Component | Source | Destination |\n|-----------|--------|-------------|\n| Validation script | `.claude/scripts/validate.sh` | `\u003ctarget\u003e/.claude/scripts/` |\n| Validate command | `.claude/commands/validate.md` | `\u003ctarget\u003e/.claude/commands/` |\n| Generate command | `.claude/commands/generate-file.md` | `\u003ctarget\u003e/.claude/commands/` |\n| PostToolUse hook | `hooks/hooks.json` → PostToolUse section | `\u003ctarget\u003e/.claude/settings.json` |\n| Design skill | `.claude/skills/` | `\u003ctarget\u003e/.claude/skills/` |\n\n## Reference\n\n- [Official Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code/overview)\n- [Skills Overview](https://docs.anthropic.com/en/docs/claude-code/skills)\n- [Agent Skills Best Practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)\n- [Anthropic Skills Repository](https://github.com/anthropics/skills)\n- [Claude Code GitHub Repository](https://github.com/anthropics/claude-code)\n- [Agent Skills Specification](https://agentskills.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpxuser%2Fclaude-code-devkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvpxuser%2Fclaude-code-devkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvpxuser%2Fclaude-code-devkit/lists"}