Helps users scaffold new projects with production-ready files: README.md, AGENTS.md (agent memory), and CI/CD pipelines (GitLab CI, GitHub Actions, or both). Handles tech stack selection, coding standards ingestion, quality level configuration (demo vs. production), and SDD framework integration (OpenSpec, SpecKit, or GSD). Documentation is generated in Chinese (中文) by default, with support for other languages upon request. Use this skill whenever a user wants to create a new project, initialize a repository, set up CI/CD, choose a spec-driven development workflow, scaffold project files, or asks about project structure and agent memory files. Even if the user only asks about one part (e.g., "set up CI/CD" or "create AGENTS.md"), use this skill — it ensures all files stay consistent with each other.
name: project-initializer
description: Helps users scaffold new projects with production-ready files: README.md, AGENTS.md (agent memory), and CI/CD pipelines (GitLab CI, GitHub Actions, or both). Handles tech stack selection, coding standards ingestion, quality level configuration (demo vs. production), and SDD framework integration (OpenSpec, SpecKit, or GSD). Documentation is generated in Chinese (中文) by default, with support for other languages upon request. Use this skill whenever a user wants to create a new project, initialize a repository, set up CI/CD, choose a spec-driven development workflow, scaffold project files, or asks about project structure and agent memory files. Even if the user only asks about one part (e.g., "set up CI/CD" or "create AGENTS.md"), use this skill — it ensures all files stay consistent with each other.
Project Initializer
A skill for scaffolding new projects with consistent README.md, AGENTS.md, and CI/CD pipelines — all wired together with an SDD (Spec-Driven Development) framework.
Overview
The skill does five things:
Interview — Understand the project's goals, tech stack, coding standards, quality requirements, CI platform(s), and preferred SDD workflow.
Generate — Create README.md, AGENTS.md, and CI pipeline file(s) from templates.
Integrate — Install SDD framework tools and initialize project structure; wire coding standards and quality checks into the CI pipeline.
Tag — Embed a machine-readable project identity tag in AGENTS.md so server-side CI can verify the project was properly initialized.
Verify consistency — Make sure all generated files agree with each other (same tech stack, same quality gates, same SDD expectations).
CRITICAL — Template Fidelity: Reproduce every CI pipeline template verbatim. Substitute only the {{PLACEHOLDER}} tokens. Do not remove, merge, rename, or omit any stages, jobs, or comment blocks. The complete job set in each template is the minimum viable pipeline; dropping any job will break SDD checks, project-tag validation, or coverage gates. For demo projects, dial down strictness through placeholder values (e.g., set {{COVERAGE_THRESHOLD}} to 0, {{SECURITY_SCAN_CMD}} to echo "skipped") — never by removing jobs.
After gathering information, generate files. Use the templates in assets/templates/ as starting points and fill in the placeholders.
Path resolution — read this before running any script:
<skill_dir> = the directory that contains this SKILL.md file (e.g. .agents/skills/project-initializer). All script paths below are relative to <skill_dir>.
<project_root> = the root of the project being initialized — pass . if you are already inside it, or the absolute path if not. Never pass a path outside the project the user is working on.
File locations:
README.md — project root
AGENTS.md — project root
.gitlab-ci.yml — project root (if GitLab CI selected)
{{IGNORE_TAG_DOCS}} — the git commit ignore tag reference for the chosen framework (see reference docs)
{{CODING_STANDARDS_SUMMARY}} — see Coding Standards Composition section above
{{INITIALIZED_DATE}} — today's date in YYYY-MM-DD format
{{MAIN_BRANCH}} — release branch name
Language: Generate this file in the language chosen in Phase 1 (default: Chinese/中文).
Important: AGENTS.md is a living document. Keep it minimal at creation time. Agents should append to it during development but never remove existing entries. The initial version is just the skeleton — it will grow.
Coding Standards Composition
If the user provided coding standards:
Read the content (from the pasted text or the file path).
Extract the key rules relevant to: naming conventions, file structure, formatting, forbidden patterns, and required patterns.
Summarize them into the ## Coding Standards section of AGENTS.md (concise bullet-point form — the full doc lives separately).
If the standards specify a linter/formatter config, reference it in the {{LINT_CMD}} for CI (e.g., eslint --config .eslintrc.json, ruff check --config pyproject.toml).
If the user provided a file path, also add a reference to that file in AGENTS.md so agents know where the canonical source is.
If no standards were provided, write a minimal placeholder in the Coding Standards section appropriate for the tech stack (e.g., "Follow PEP 8" for Python, "Follow Airbnb JavaScript Style Guide" for JS).
.gitlab-ci.yml
Read assets/templates/gitlab-ci.template.yml. Fill in:
{{DOCKER_IMAGE}} — appropriate base image for the tech stack
This installs the appropriate runtime variant (.sh on Linux/macOS, .js as fallback, .ps1 on Windows) of check_project_tag and check_sdd_<framework> into <project_root>/scripts/. Do not manually recreate or copy-paste script files — the install script guarantees the exact asset versions are used without modification. Pass --dry-run first to verify what will be copied.
Read assets/templates/github-actions.template.yml. Fill in the same placeholders as the GitLab template — the values must be identical to ensure both pipelines enforce the same standards.
Phase 3: SDD Framework Installation
MANDATORY — do not skip or substitute manually.
You MUST run the script below. Do NOT create SDD framework directories or documents by hand. Manually created files will be incomplete, wrongly structured, and will fail CI checks. If the script encounters an error, report it to the user — do not work around it by creating files yourself.
Resolve <skill_dir> (the directory containing this SKILL.md) and run:
If you are already inside the project directory, <project_root> is ..
Determining the --ai-provider value: Use the name of the AI agent currently running this skill (e.g. claude, copilot, gemini, opencode, codex). You know this from your own identity — pass it as-is.
For SpecKit only — --script-shell parameter: Choose the shell for generated scripts:
sh (default): Unix/shell scripts — use for Linux/macOS CI runners
ps: PowerShell scripts — use for Windows CI runners
This script runs all frameworks non-interactively:
OpenSpec: openspec init --tools <tool_id> — --ai-provider mapped to OpenSpec's tool ID: claude, opencode, codex, gemini, windsurf, qwen, codebuddy, kilocode use the same name; copilot→github-copilot; cursor-agent→cursor; roo→roocode; all others→all
SpecKit: specify init . --ai <provider> --here --force --script <shell> — passes the provider name and shell choice directly
GSD: npx -y get-shit-done-cc@latest --<runtime> --local — --ai-provider is mapped to a runtime flag: claude→--claude, opencode→--opencode, codex→--codex, all others→--claude
The script also:
Installs the framework CLI tool (npm, uv, or npx as appropriate) if not found
Initializes framework-specific directories
For OpenSpec: initializes openspec/specs/ and openspec/changes/
For SpecKit: initializes specs/ (auto-numbered) and memory/constitution.md
For GSD: initializes .planning/ with PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, config.json
Always place it as the very first content in AGENTS.md (before the # heading)
Use the actual initialization date (today)
sdd_framework — lowercase identifier: openspec, speckit, or gsd
ci_platforms — comma-separated, no spaces: gitlab, github, or gitlab,github
Do not modify this block after creation except through a deliberate re-initialization
The CI check script (assets/scripts/check_project_tag.sh) reads this tag and exits non-zero if it is missing or malformed. It is installed automatically by the install_scripts.py step described in Phase 2 — check_project_tag is always included regardless of the chosen SDD framework. The framework's initialize script (Phase 3) must complete successfully before this tag is validated.
Phase 6: Consistency Verification
After generating all files, perform this checklist:
AGENTS.md starts with a valid <!-- @project-initializer tag
sdd_framework in tag matches chosen framework
ci_platforms in tag matches files actually generated
Docker/runner image in CI file(s) matches tech stack
AGENTS.md tech stack section matches README.md
Coverage threshold in CI file(s) matches AGENTS.md → Quality Standards
SDD framework name consistent across all generated files
The correct SDD check script is referenced (OpenSpec/SpecKit/GSD)
Both CI platform files (if both generated) use identical quality thresholds
Branch name in CI rules matches the stated main branch
SDD framework initialized successfully (Phase 3)
OpenSpec: openspec/specs/ and openspec/changes/ exist
All script paths are relative to <skill_dir> (the directory containing this SKILL.md). <project_root> is the project's root — use . if already inside it.
scripts/install_scripts.py — copies check scripts into <project_root>/scripts/
Must be run — do not manually create SDD directories. Installs the framework CLI non-interactively, sets up directories. Add --dry-run to preview.
Template files
assets/templates/README.template.md
assets/templates/AGENTS.template.md
assets/templates/gitlab-ci.template.yml
assets/templates/github-actions.template.yml
Check scripts
Each check is available in three runtime variants, stored in the skill's assets/scripts/ directory. The install_scripts.py command copies these into the target project's scripts/ directory — which variant gets invoked in CI depends on the runner OS and what's available.
Script
Shell (Linux/macOS)
PowerShell (Windows/cross-platform)
Node.js (any platform)
Project tag
check_project_tag.sh
check_project_tag.ps1
check_project_tag.js
OpenSpec
check_sdd_openspec.sh
check_sdd_openspec.ps1
check_sdd_openspec.js
SpecKit
check_sdd_speckit.sh
check_sdd_speckit.ps1
check_sdd_speckit.js
GSD
check_sdd_gsd.sh
check_sdd_gsd.ps1
check_sdd_gsd.js
Selecting which variant to use in CI
When generating CI pipeline files, choose the invocation command based on the project's runner environment:
Runner environment
CI invocation
Linux / macOS (bash available)
bash scripts/check_sdd_<fw>.sh
Windows (PowerShell 7+ available)
pwsh scripts/check_sdd_<fw>.ps1
Any (Node.js ≥ 18 available)
node scripts/check_sdd_<fw>.js
Unknown / mixed
Use Node.js — it works everywhere Node.js is installed
The Node.js variants are the most portable choice if the runner environment is uncertain. They require no npm dependencies — only the Node.js built-in modules (fs, path, child_process).
The GitLab CI and GitHub Actions templates default to the shell variant. If the user's CI runners are Windows-based or they prefer Node.js, update the script: / run: lines accordingly. All three variants implement identical logic and exit codes.
