cookiecutter
Use when adding, changing, testing, or debugging Cookiecutter templates, including cookiecutter.json variables, Jinja-rendered files, hooks, _copy_without_render, optional feature cleanup, and generated-project validation.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- cookiecutter
- license
- MIT
- metadata
- { "tags": "cookiecutter,templates,jinja,scaffolding", "version": "0.1.0", "category": "Developer Tooling", "displayName": "Cookiecutter" }
- description
- Use when adding, changing, testing, or debugging Cookiecutter templates, including cookiecutter.json variables, Jinja-rendered files, hooks, _copy_without_render, optional feature cleanup, and generated-project validation.
- compatibility
- Codex, Claude Code, and other Agent Skills-compatible clients.
02 资源文件 1
- 资产文件assets/app-icon.png68.0 KB
03 SKILL.md 正文
Cookiecutter Template Work
Use this skill before changing a repository that has cookiecutter.json,
hooks/, or a generated project directory such as
{{ cookiecutter.project_slug }}/.
First Pass
- Read the repo instructions,
README.md,cookiecutter.json, existing tests, and any hooks before editing. - Identify the template root and the generated project root. Make changes in the template files, not in one rendered sample.
- Search for the relevant Cookiecutter variables and feature flags with
rgbefore adding new ones. - Check how the repo validates rendered projects. Prefer existing render tests and smoke-check commands over inventing a separate validation path.
Template Boundaries
cookiecutter.jsonis the user-facing interface. Every new prompt, default, derived value, private value, and choice should be deliberate and documented where the repo documents options.- The generated project directory may itself contain Jinja in file names and paths. Treat both file contents and paths as render surfaces.
- Follow the repo's current variable style. If it already uses
y/nstrings, keep using that style for new feature flags. If it uses Cookiecutter boolean values, keep those as real JSON booleans. - Optional features must be valid in both enabled and disabled states. Remove or gate app files, imports, URL routes, settings, dependencies, docs, tests, workflows, and migrations together.
- Do not add maintainer-specific names, local paths, secrets, or one-agent assumptions to generated output.
Jinja Rules
- Keep rendered files valid in their target language: Python, JSON, TOML, YAML, shell, Markdown, HTML, JavaScript, or CSS.
- Watch for dangling commas after conditional blocks in JSON, TOML, Python data structures, YAML lists, package manifests, and GitHub Actions.
- Use whitespace control (
{%- ... -%}) only when it improves rendered syntax or formatting. Validate the rendered result, not only the template source. - Use safe serialization for strings inserted into code or data files. Prefer
the repo's existing JSON/Jinja filter pattern, such as
|tojson, when it is already used. - If generated output must preserve literal Jinja, template syntax, or agent
placeholders, either escape the braces, wrap the content in raw blocks, or add
the path to
_copy_without_render. _copy_without_renderprevents rendering file contents, but paths are still rendered. Include both directory and recursive glob entries when a whole tree must be copied verbatim.
Hooks
- Put Cookiecutter hooks in
hooks/aspre_prompt,pre_gen_project, orpost_gen_projectscripts. Prefer Python for cross-platform templates unless the repo is intentionally platform-specific. pre_gen_projectandpost_gen_projectrun from the generated project root and can use rendered Cookiecutter variables.- Make hooks deterministic, idempotent, and relative-path based. Avoid network calls, secrets, interactive prompts, and machine-local paths.
- A non-zero hook exit stops generation and Cookiecutter cleans the generated directory. Fail early for invalid user input; be defensive for cleanup.
- Use post-generation cleanup for whole optional files or directories. Use inline Jinja for small syntax-aware changes inside files that must remain.
Testing
- Add or update tests that render the template with explicit context values. Cover each changed option both enabled and disabled when practical.
- Include assertions for absence, not only presence: disabled optional features should not leave imports, dependencies, routes, docs, workflows, migrations, or placeholder text behind.
- Exercise the real Cookiecutter CLI when changing generation behavior, hooks, template selection, or command-line assumptions.
- For runtime behavior changes, generate a project in a temp directory and run that project's documented checks.
- Inspect rendered files that are sensitive to syntax: JSON, TOML, YAML, Python modules, shell scripts, and package manifests.
Common Failure Patterns
- Jinja renders syntactically valid template source into invalid generated code.
- A disabled option removes files but leaves settings, imports, URLs, dependencies, docs, tests, migrations, or CI references.
- Literal
{{ ... }}placeholders intended for the generated project are consumed by Cookiecutter. - Hooks assume the template repo as the working directory instead of the generated project root.
- Tests render one happy-path context but miss another supported option combination.
- Generated files include local paths, personal names, secrets, or assumptions about a specific AI tool.
Definition of Done
- Template changes are made at the template level.
- Relevant enabled and disabled option combinations render successfully.
- The generated output has no stale placeholders, syntax errors, orphan imports, or hard-coded maintainer-specific values.
- The repo's template test suite passes.
- Docs and changelog entries are updated when users or generated-project contributors need to know about the change.
References
- Official documentation: https://cookiecutter.readthedocs.io/en/stable/
- Upstream repository: https://github.com/cookiecutter/cookiecutter
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.