Optimization: This skill uses on-demand loading. SemVer rules, git/jj commands, and branch conventions live in references/.

Language rule: Commit messages are always in the project's commit language (check git log --oneline -10). If mixed, default to English. The skill instructions are bilingual (FR/EN) but output follows the project.

Conventional Commits -- Ghostwriter

"A commit message is a letter to your future self. Write it in your voice, not a machine's."

Reference: https://www.conventionalcommits.org/en/v1.0.0/

Rule zero: Authorship

NEVER add `Co-authored-by: Claude` or any AI trailer. The commit belongs entirely to the person who asked. No Co-authored-by, Generated-by, AI-assisted, or equivalent trailers. Ever.

Ghost mode

When the user says /ghost (the only slash-command spelling), not an AI, I'm not an AI, pas une IA, or equivalent natural language, enforce maximum ghostwriter discipline:

• Write as the user's quiet maintainer, not as an assistant.
• Do not mention AI, agents, prompts, models, Claude, Codex, ChatGPT, OpenAI, or

Anthropic in commits, branches, tags, changelogs, PR text, release notes, or generated repo files unless the repository itself is explicitly about those tools.

• Prefer direct project vocabulary over meta-process language.
• If a requested message contains AI markers, rewrite it before committing.
• Run the full-directory AI marker audit. In ghost mode, staged marker entries

are not allowed to remain unless reclassified as product-fixture with a short reason tied to source, tests, packaging, or documented product behavior.

Ghostwriter style

Claude is the ghostwriter. The message is signed by the user, written in their voice.

Banned words: comprehensive, robust, leverage, utilize, enhance, streamline, facilitate, in order to, as part of, to ensure that.

Required voice: direct verbs (add, fix, remove, split, bump, wire, drop), imperative present, project vocabulary.

Commit format

<type>[scope][!]: <description>

[body]

[footer(s)]

Types

If a change spans multiple types, split into multiple commits.

Description (subject line)

• Imperative present: add, fix, remove (never added, fixes, removing)
• No capital first letter: feat: add retry logic -- not feat: Add retry logic
• No trailing period
• Max 72 characters (entire subject line including type)
• Precise and factual: what + optionally why in one phrase

Body

• Separated from description by one blank line (mandatory)
• Explain the why, not the how (the code shows the how)
• Free paragraphs, wrap at 72 characters
• Can reference issues, tickets, PRs

Footers

BREAKING CHANGE: <what breaks>
Refs: #123, #456
Closes: #789

No Co-authored-by: Claude or similar. Ever.

Breaking changes

Signal with ! before : and/or BREAKING CHANGE: footer:

feat(api)!: remove legacy v1 endpoints

BREAKING CHANGE: /api/v1/* routes no longer served. Migrate to /api/v2/*.

AI marker file audit

Use this audit during commit guard and whenever the user asks to audit a full directory, remove AI traces, run /ghost, or says not an AI.

Scan the whole target directory, not only the staged diff. Detection must be agnostic: do not rely only on a fixed allow/deny list. Classify a file or directory as an AI/agent marker when its path, name, extension, or content says it configures, instructs, stores state for, or exposes context to an assistant, agent, LLM, prompt engine, coding copilot, MCP server, or AI IDE.

Minimum detection method:

1. Inventory tracked and untracked files, excluding .git, vendored dependency

trees, build outputs, binary blobs, and large generated artifacts.

1. Flag by path/name signals. Examples, not an exhaustive list: CLAUDE.md,

GEMINI.md, AGENTS.md, llms.txt, llms-full.txt, .cursorrules, .cursor/, .windsurf/, .aider*, .continue/, .junie/, .claude/, .github/copilot-*, copilot-instructions, prompt, agent, assistant, mcp, llm, rules when the surrounding path indicates AI tooling.

1. Flag by content signals even when the filename is neutral: frontmatter or

prose mentioning AI-agent instructions, tool-specific configuration, prompt/rule injection, model/provider setup, MCP servers, code-assistant memory, conversation history, or instructions intended for Claude, Codex, Cursor, Copilot, Aider, Gemini, Windsurf, OpenCode, Devin, Jules, Continue, or equivalent tools.

1. Classify each hit:

• marker: AI/agent config, memory, instruction, prompt, or history file.
• product-fixture: legitimate source/test fixture in a repo whose product

is AI/agent tooling, skill distribution, or assistant integration.

• documentation-only: ordinary docs that mention AI as a product topic but

do not configure an assistant.

• false-positive: unrelated use of words like agent, prompt, or

model.

1. Report both staged and full-directory results. The commit guard may proceed

only when all staged marker entries are removed or reclassified as product-fixture with a short reason.

Example shell probes to seed the audit, not to replace judgment:

find . -name .git -prune -o -type f -print \
  | rg -i '(^|/)(CLAUDE|GEMINI|AGENTS|llms(-full)?|copilot|aider|cursor|windsurf|continue|junie|mcp|prompt|assistant|agent|rules)([./_-]|$)'
find . -name .git -prune -o -type d -print \
  | rg -i '(^|/)\.(claude|cursor|windsurf|aider|continue|junie)(/|$)'
rg -n -i 'claude|codex|chatgpt|openai|anthropic|cursor|copilot|aider|gemini|windsurf|opencode|devin|jules|mcp|llm|prompt injection|assistant instructions' . \
  --glob '!**/.git/**' \
  --glob '!**/node_modules/**' \
  --glob '!**/target/**' \
  --glob '!**/dist/**'

Policy:

• For ordinary product repos, remove marker files from the commit 100%. If the

content is useful, move it first into standard docs such as CONTRIBUTING.md, docs/architecture.md, docs/index.md, or repo-specific operator docs, then delete the marker file.

• If marker files are already tracked, treat their removal as part of the guard

when the user asked for ghost/no-AI cleanup or full-directory audit.

• If a marker file is unrelated to the user's requested commit and deleting it

would be a destructive scope expansion, stop and report the exact marker paths instead of silently committing around them.

• The only exception is a repository whose product domain is explicitly

AI/agent tooling, skill distribution, or assistant integration. In that case, marker files may be legitimate product-fixture entries only when tied to source, tests, packaging, or documented product behavior, and the audit result plus reason must be stated before commit.

• Never add new marker files in ghost mode.

Commit Guard

Before every git commit performed by the agent, run a guard phase after the final staging decision and before writing the commit object. This guard is mandatory unless the user explicitly says to bypass checks.

Minimum guard:

1. Inspect worktree ownership with git status --short. Do not stage or revert

unrelated user changes.

1. Inspect exactly what will be committed with git diff --cached --name-status

and git diff --cached --stat. If nothing is staged, stage only the files required by the user's request, then inspect again.

1. Run git diff --cached --check. Fix whitespace/conflict-marker failures

before committing.

1. Run the AI marker file audit on the full target directory. Remove staged

entries classified as marker, or stop and report them if removing tracked files is outside the user's requested scope. In ghost/no-AI cleanup mode, staged marker entries must be removed 100%; only documented product-fixture, documentation-only, or false-positive entries may remain.

1. Scan the staged diff and commit message for AI text markers: Co-authored-by,

Generated-by, Generated with, AI-assisted, Claude, Codex, ChatGPT, OpenAI, Anthropic, Cursor, Aider, Devin, Jules, Windsurf. If a marker is not part of the product domain, remove it.

1. Run the repo's established fast validation when it is discoverable and

relevant. Examples: python3 scripts/validate_skills.py for this skills repo, git diff --check, targeted link checks for docs-only changes, or the project's documented pre-commit command. Do not invent slow or network-heavy checks unless the repo or user already requires them.

1. If any guard step fails, do not commit. Fix the issue or report the blocker

with the exact failing command.

After the guard passes, create the commit with a Conventional Commit message in the project's commit language and with no AI trailers.

Workflow

Step 1 -- Analyze the diff and detect language

Before writing a commit message:

1. Complete the Commit Guard above.
2. Read git diff --staged (or the changes the user shared).
3. Read git log --oneline -10 for context, style, AND language.
4. Detect commit language: if existing commits are in French → write in French. If English → English. If mixed → follow the majority. NEVER switch language — a developer who wrote 14 commits in French doesn't suddenly switch to English.
5. Identify: is this one logical change or multiple? If multiple, suggest splitting.

Language examples:

# History is French → commit in French
git log: "fix(ci): corrige perte de variable dans subshell"
NEW:     "fix(security): externalise le mot de passe healthcheck"

# History is English → commit in English
git log: "fix(ci): fix variable loss in subshell"
NEW:     "fix(security): externalize healthcheck password"

Step 2 -- Classify

Determine the type. When in doubt:

• Does it add user-visible functionality? -> feat
• Does it fix a bug? -> fix
• Does it change behavior without adding or fixing? -> refactor
• Does it only change tests? -> test
• Does it only change docs? -> docs
• Does it only change CI? -> ci
• Does it only bump deps? -> chore(deps) or build(deps)

Step 3 -- Scope

Choose the most specific scope:

• Module name: auth, router, cache, dlp
• Layer: api, db, ui, cli
• Dependency: deps
• No scope if truly project-wide

Step 4 -- Write

Apply ghostwriter rules:

1. Subject: imperative, lowercase, <=72 chars, no filler
2. Body (if needed): why this approach, not what the diff says
3. Footers: refs, breaking changes, closes
4. No AI trailers

Step 5 -- Deliver

Use HEREDOC for multi-line messages:

git commit -m "$(cat <<'EOF'
fix(auth): handle expired tokens

Remove the silent swallow of TokenExpiredError. Callers now
receive a 401 with Retry-After header.

Refs: #88
EOF
)"

Read references/commands.md for full git and jj command reference.

SemVer and releases

Read references/semver.md for SemVer 2.0.0 rules, tag commands, version bump resolution, and CHANGELOG format.

Branch naming

Read references/branches.md for branch naming conventions and examples.

Anti-patterns

AI marker audit (history + files cleanup)

When invoked with --audit-markers, /ghost, not an AI, or when the user asks to clean AI traces from a project or audit a full directory, apply the agnostic AI marker file audit above first. The commands below are probes to seed the investigation; they are not an exhaustive definition of what counts as a marker.

Step 1 -- Detect commit trailers

Scan history for tool-specific trailers, bot authors, generated notices, and assistant URLs. Treat the patterns as examples and add equivalent project-local signals when found:

# Trailers (all AI tools)
git log --all --format="%H %s" --grep="Co-authored-by\|Co-Authored-By\|Generated by\|Generated with\|Generated-by\|AI-assisted" | \
  grep -iE "claude|copilot|opencode|codex|cursor|aider|gemini|devin|windsurf|anthropic|openai"

# Bot authors (Copilot, Devin, Jules)
git log --all --format="%H %an" | grep -iE "\[bot\]|copilot|devin-ai|jules"

# Aider author suffix
git log --all --format="%H %an" | grep "(aider)"

# PR footers in merge commits
git log --all --merges --format="%H %b" | grep -iE "claude.com/claude-code|cursor.com|Generated with|<!-- Cursor -->"

Known trailers by tool:

Step 2 -- Detect AI marker files

# Path/name probe, then classify each hit with the agnostic audit rules.
find . -name .git -prune -o -type f -print \
  | rg -i '(^|/)(CLAUDE|GEMINI|AGENTS|llms(-full)?|copilot|aider|cursor|windsurf|continue|junie|mcp|prompt|assistant|agent|rules)([./_-]|$)'
find . -name .git -prune -o -type d -print \
  | rg -i '(^|/)\.(claude|cursor|windsurf|aider|continue|junie)(/|$)'

# Content probe for neutral filenames that still carry assistant instructions.
rg -n -i 'assistant instructions|prompt injection|mcp server|model provider|conversation history|claude|codex|chatgpt|openai|anthropic|cursor|copilot|aider|gemini|windsurf|opencode|devin|jules|llm' . \
  --glob '!**/.git/**' \
  --glob '!**/node_modules/**' \
  --glob '!**/target/**' \
  --glob '!**/dist/**'

Step 3 -- Detect AI markers in .gitignore

Check if AI config files are already gitignored. If NOT, recommend adding them.

Step 4 -- Report

## AI Marker Audit -- {project}

### Commits: N trailers found
| Tool | Count | Branches |
| ... |

### Files: N candidate markers found
| File | Classification | Reason |
| ... |

### Branch names: N AI-prefixed branches
| Branch | Tool |
| ... |

Step 5 -- Propose cleanup options

Step 6 -- Recommend

Step 7 -- Preventive .gitignore

Recommend adding private assistant state, caches, and local IDE integration to .gitignore when they are not legitimate product fixtures. Do not present this as an exhaustive list:

# AI tool config (not project documentation)
.cursor/
.cursorrules
.cursorignore
.cursorindexignore
.windsurf/
.windsurfrules
.codeiumignore
.aider*
.claude/
.continue/
.junie/

Note: root instruction files such as CLAUDE.md, GEMINI.md, AGENTS.md, or equivalents are usually absorbed into standard docs by cli-forge-doc and then deleted. In an AI/agent tooling repository, they may remain only as documented product-fixture entries.

Never run filter-repo or force push without explicit user approval.

Dynamic Handoffs

Rule: Recommend, don't auto-execute.

What this skill does NOT do

• Does not rewrite history autonomously -- destructive cleanup such as

filter-repo, force push, or removing unrelated tracked markers needs explicit user approval

• Does not enforce commit hooks -- it provides the message format, not pre-commit validation
• Does not manage CI/CD -- that's cli-forge-pipeline's job
• Does not generate changelogs automatically -- it provides the format, the user generates

Integration with other cli-* skills

Checklist (internal, before delivering a message)

[ ] Language matches git log history (FR stays FR, EN stays EN)
[ ] Type correct from allowed list
[ ] Scope relevant (or absent if not applicable)
[ ] Scope style matches history (security vs sec, ci vs pipeline)
[ ] ! and/or BREAKING CHANGE footer if breaking
[ ] Description: imperative present, lowercase, no period, <=72 chars
[ ] Body separated by blank line if present
[ ] Valid footers (token: value)
[ ] NO Claude / AI / co-author trailer
[ ] Atomic commit (one logical change)
[ ] Human voice (no banned words)