Custom Skill Guides

Custom skill guides let you extend built-in skills with your own instructions — without modifying the plugin itself. You can add steps that run before or after the built-in workflow, or inject rules that apply throughout.

Location

Local directories override global directories with the same name.

Managing guides with cf guide

The coding-friend-cli ships with a cf guide command to scaffold and inspect custom guides without hand-creating directories.

# Scaffold a new local custom guide for a built-in skill
cf guide create cf-commit
# → .coding-friend/skills/cf-commit-custom/SKILL.md  (with Before/Rules/After template)

# List all custom guides in the current project
cf guide list

• cf guide create <skill-name> validates that the target skill actually exists in the installed plugin (or dev checkout) before creating the scaffold, so you can't accidentally create an orphaned guide. It won't overwrite an existing file.
• cf guide list shows every *-custom/SKILL.md under .coding-friend/skills/, marks each one with a green ✔ if the underlying skill is found, or a yellow ⚠ if the guide is orphaned (the skill no longer exists — e.g. renamed or removed).

Both commands operate on the local project scope. For global guides, create the file manually under ~/.coding-friend/skills/<skill-name>-custom/SKILL.md.

Format

A custom guide is a SKILL.md file inside a <skill-name>-custom/ directory, with up to 3 optional sections:

## Before

- Steps to run BEFORE the built-in workflow starts

## Rules

- Additional rules applied THROUGHOUT the workflow

## After

- Steps to run AFTER the built-in workflow completes

All sections are optional — include only what you need.

How it works

Every cf-* skill has a Step 0 that runs a bash script (load-custom-guide.sh). This script checks for a custom guide in the local path first, then the global path. If found, it outputs the guide content, and the skill integrates the sections into its workflow:

• ## Before → executes before the first step
• ## Rules → applies as additional rules throughout all steps
• ## After → executes after the final step

The guide content becomes a direct tool result that the model reads inline — ensuring it is always followed.

Custom guides are loaded on-demand — only when the corresponding skill runs. Changes to a guide take effect on the next skill invocation (no /clear needed).

Examples

Simple: enforce conventions on /cf-commit

.coding-friend/skills/cf-commit-custom/SKILL.md:

## Before

- Check branch naming convention (must match `feat/XX-*` or `fix/XX-*`)

## Rules

- Always include JIRA ticket number from branch name in commit subject
- Scope should match the top-level directory of changed files

## After

- Run tests if commit type is `feat:` or `fix:`

Advanced: turn /cf-ship into a version bump + release workflow

Custom guides can inject entire multi-step workflows. This example extends /cf-ship to automatically bump versions, update changelogs, and sync docs — before the standard ship workflow (verify → commit → push → PR) runs.

.coding-friend/skills/cf-ship-custom/SKILL.md:

## Before

This is a **version bump + ship** operation. Run these steps BEFORE the standard cf-ship workflow.

**Args** (optional): `[patch|minor|major] [plugin|cli|learn-mcp|learn-host]`

### Step B1: Get bump context

(run your bump-info script to detect changed packages and their versions)

### Step B2: Confirm bump level

If level not in args, analyze the changes and suggest patch/minor/major. Ask the user to confirm.

### Step B3: Bump version files

For each package that needs bumping, run your bump script.

### Step B4: Update changelogs

Collect commits since last tag, write entries under `## v{version} (unpublished)`.

### Step B5: Print summary table

Then proceed with the **standard cf-ship workflow** (verify → commit → push → PR).

## Rules

- Published tags on `origin` = single source of truth. Run `git fetch --tags` first.
- NEVER bump if file version > tag version — only update changelog.
- Do NOT create git tags — that happens during `/release`.
- NEVER add duplicate changelog entries. One feature = one bullet.

This approach uses helper scripts (stored alongside the SKILL.md) to handle version detection and file updates. The ## Before section runs the bump workflow, then hands off to /cf-ship's built-in verify → commit → push → PR flow.

For a complete real-world example with scripts, see the Coding Friend project's own cf-ship-custom guide.