Custom Templates

Custom Templates

How to extend ai-coding-ok with your own templates — for organization-specific conventions, compliance requirements, or specialized project types.

---

When to create custom templates

Scenario	Approach
Your team has standard coding conventions	Modify coding-standards.md after install
Your org has compliance requirements	Add a COMPLIANCE.md template
You work with a specific tech stack repeatedly	Create a templates/ variant for your stack
You want to share conventions across repos	Create a shared template repo

---

Approach 1: Modify after install (simplest)

After installing ai-coding-ok, customize the installed files directly:

# Edit the coding standards for your team
vim .github/agent/coding-standards.md

# Add your compliance rules
echo "## SOC2 Requirements" >> .github/agent/memory/project-memory.md

# Commit the changes
git add .github/agent/
git commit -m "chore: customize ai-coding-ok for team conventions"

Pros: Simple, no framework changes needed.
Cons: Must repeat for each project. Changes may conflict with upgrades.

---

Approach 2: Add a new template file

Add a custom template to the ai-coding-ok repo and reference it in the install process:

Step 1: Create the template

# Create in both languages
mkdir -p templates/en/my-org
mkdir -p templates/zh/my-org

Create templates/en/my-org/COMPLIANCE.md:

<!-- ai-coding-ok: v3.1.0 -->
# {{project-name}} — Compliance Requirements

## SOC2 Controls

| Control | Requirement | Implementation |
|---------|-------------|----------------|
| Access Control | All endpoints require auth | Enforced by {{framework}} middleware |
| Audit Logging | All data mutations logged | Using {{database}} audit table |
| Encryption | Data encrypted at rest | Using {{database}} encryption |

Step 2: Update the install flow

In SKILL.md, add to the "What this skill installs" section and the placeholder replacement list.

Step 3: Update install scripts

In install.sh and install.py, add the new file to the copy list.

Step 4: Update verify.sh

REQUIRED_FILES+=("my-org/COMPLIANCE.md")

---

Approach 3: Tech stack variant templates

Create a variant of the full template set for a specific tech stack:

templates/
├── en/
│   ├── default/          ← Standard templates
│   └── react-fastapi/    ← Variant for React + FastAPI projects
│       ├── AGENTS.md
│       ├── .github/agent/coding-standards.md  ← JS + Python conventions
│       └── ...
└── zh/
    └── ...

The variant overrides the default files that need tech-stack-specific content.

---

Approach 4: Organization template repo

For teams that want to share templates across many repos:

# Create a shared template repo
git clone git@github.com:your-org/ai-coding-ok-templates.git

# Structure:
your-org-templates/
├── coding-standards.md      ← Override the default
├── project-memory.md        ← Add org-specific sections
├── COMPLIANCE.md            ← Custom file
└── install.sh               ← Wrapper that installs ai-coding-ok + your templates

The wrapper script:

#!/usr/bin/env bash
# install.sh — install ai-coding-ok + org templates

# 1. Install base ai-coding-ok
bash /path/to/ai-coding-ok/install.sh --copilot

# 2. Overlay org templates (preserve ai-coding-ok placeholders)
cp -n coding-standards.md .github/agent/coding-standards.md
cp -n project-memory.md .github/agent/memory/project-memory.md
cp -n COMPLIANCE.md .github/agent/COMPLIANCE.md

echo "✅ ai-coding-ok + org templates installed"

---

Template file conventions

File naming

• Use UPPER_CASE.md for root-level files
• Use kebab-case.md for subdirectory files
• Match the existing naming convention in the target directory

Placeholder naming

• English: {{kebab-case-name}} (e.g., {{org-name}})
• Chinese: {{中文名称}} (e.g., {{组织名称}})
• Reuse existing placeholders where possible
• Document new placeholders

Version marker

Every template file MUST start with:

<!-- ai-coding-ok: v3.1.0 -->

Section structure

Follow the existing section hierarchy:

• # — Page title
• ## — Major sections
• ### — Sub-sections
• #### — Details

---

Testing custom templates

Test install

# Create a test project
mkdir /tmp/test-project
cd /tmp/test-project

# Run install with your custom templates
bash /path/to/your-templates/install.sh

# Verify
bash /path/to/ai-coding-ok/scripts/verify.sh

Test PDCA

In the test project, ask the AI to do a small task and verify:

1. Memory files are read before coding
2. Memory Updates section appears in the response
3. Custom template content is referenced

---

Custom template checklist

• Created in both templates/en/ and templates/zh/
• Uses existing placeholders where possible
• New placeholders documented
• Version marker on line 1
• Added to SKILL.md install list
• Added to install.sh / install.py
• Added to verify.sh required files
• Tested with a fresh install
• Tested with an upgrade

---

Next steps

• Template System — understand the base template architecture
• Placeholder System — placeholder reference
• Contributing — how to contribute templates back to ai-coding-ok