# codegen-skill

**Repository Path**: eyupaopao/codegen-skill

## Basic Information

- **Project Name**: codegen-skill
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-20
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# codegen-skill

AI-agent-facing code generation for Cursor, Claude Code, and MCP clients.

面向 Cursor、Claude Code 和 MCP 客户端的 AI 代码生成工具：先尝试命中可复用模板；如果没有命中，AI 写出代码后把这个模式保存为模板；下一次类似需求直接渲染生成，减少重复 token 消耗。

## Why

`codegen-skill` is built for repeated scaffolding work: controllers, services, DTOs, handlers, lists, forms, and team-specific boilerplate. It does not call an LLM itself. It gives your AI tool a local template memory through three actions:

- `generate`: render an existing template from tags and variables.
- `saveTemplate`: save a reusable pattern after a miss or after writing canonical boilerplate.
- `listTemplates`: inspect available user/project templates before generating or saving.

中文：它不是一个内置 LLM 的 SaaS，而是给 AI 工具使用的本地代码模板记忆层。AI 先查模板，没命中再写代码并沉淀模板，后续同类代码走确定性生成。

## Install

Requires Node.js `>=22.12.0`.

```bash
npm i -g codegen-skill
codegen-skill install --auto
```

This installs two bins:

- `codegen-skill`: CLI for install, seed, list, generate, stats.
- `codegen-mcp`: MCP stdio server for MCP-compatible clients.

If you are working from a repo clone instead of the published npm package:

```bash
pnpm install
pnpm build:protocol
pnpm -w build
pnpm exec codegen-skill install --auto
```

## First Run

Load the bundled seed templates, then generate from one of them:

```bash
codegen-skill seed
codegen-skill list
codegen-skill generate --tags typescript,controller,rest --category backend --vars '{"name":"Invoice"}' --output ./out
```

PowerShell tip: if inline JSON quoting is awkward, put variables in a file and use `--vars-file`.

```powershell
'{"name":"Invoice"}' | Set-Content .\vars.json
codegen-skill generate --tags 'typescript,controller,rest' --category backend --vars-file .\vars.json --output .\out
```

中文：首次使用建议先执行 `seed`，把内置模板复制到本机 `~/.codegen/templates/`，这样第一天就能看到 `generate` 命中效果。

## AI Workflow

The important loop is `generate miss -> saveTemplate -> generate hit`.

1. Ask the AI for a repeated slice, for example “create a TypeScript REST controller for Invoice”.
2. The AI should call `listTemplates` or `generate` with tags such as `typescript,controller,rest`.
3. If `generate` misses, the AI writes the code normally.
4. In the same turn, if that code pattern should be reused, the AI calls `saveTemplate` with explicit `scope`, tags, template files, and variables.
5. The next similar request calls `generate` again and should hit the saved template.

中文闭环：先 `generate`；未命中时不要只把代码贴出来，还要在同一轮把可复用结构交给 `saveTemplate`；下一次同类需求再 `generate`，命中模板后只传少量变量。

Example Skill/MCP intent, shown conceptually:

```json
{
  "tool": "saveTemplate",
  "scope": "user",
  "name": "ts-rest-controller",
  "tags": ["typescript", "controller", "rest"],
  "files": [
    {
      "path": "server/{{kebabCase name}}.controller.ts.hbs",
      "content": "export class {{pascalCase name}}Controller {\n  list() {\n    return [];\n  }\n}\n"
    }
  ],
  "variables": [{ "name": "name", "type": "string" }],
  "collision": "error_if_exists"
}
```

Then:

```bash
codegen-skill generate --tags typescript,controller,rest --category backend --vars '{"name":"Order"}' --output ./out
```

## Integrations

`codegen-skill install` copies the Skill artifacts to a detected target:

- Cursor Skill: `.cursor/skills/codegen/`
- Claude Code Skill: `~/.claude/skills/codegen/`
- Project-local fallback: `.cursor/skills/codegen/`

For MCP clients, configure `codegen-mcp` as a stdio server. The MCP server exposes the same `generate`, `saveTemplate`, and `listTemplates` actions as the Skill path.

中文：Cursor / Claude Code Skill 和 MCP 使用同一套核心逻辑；区别只是传输方式。MCP stdout 保持 JSON-RPC 干净，调试输出走 stderr。

## Bundled Seeds

The npm package includes starter templates under `seeds/` for:

- TypeScript backend slices
- Java, C#, Python, and Go backend slices
- React and Vue frontend slices
- Small backend task templates such as controllers and services

Use these as cold-start examples, then save your own project conventions with `saveTemplate`.

```bash
codegen-skill seed --only seed-react-list
codegen-skill seed --only seed-ts-rest-controller
```

## Verify The Package

For maintainers and local release checks:

```bash
pnpm install
pnpm build:protocol
pnpm -w build
pnpm check:npm-package
```

`check:npm-package` packs `codegen-skill`, inspects tarball contents, installs it into a temporary project, runs the CLI, installs the Skill, seeds a template, and generates a representative file. It never runs `npm publish`.

Release runbook: [`docs/RELEASE.md`](docs/RELEASE.md).

## More Docs

- Usage guide: [`docs/USAGE.md`](docs/USAGE.md)
- Release runbook: [`docs/RELEASE.md`](docs/RELEASE.md)
- Template conventions: [`CONVENTIONS.md`](CONVENTIONS.md)
- Protocol source: [`protocol/`](protocol/)
- Planning artifacts: [`.planning/`](.planning/)

## Package Layout

- `packages/codegen-skill`: public npm package with CLI, MCP server, Skill artifacts, and bundled seeds.
- `packages/core`: internal engine bundled into `codegen-skill` for the `0.1.0` npm release.

## License

MIT. See [`LICENSE`](LICENSE).