GigiKit Guides

Creating Custom Skills

Custom skills let you encode project-specific workflows, conventions, and domain knowledge into reusable packages that any agent in your GigiKit setup can activate. A skill is just a directory with a SKILL.md file — no build step, no compilation.

Directory Structure

Every skill lives under .claude/skills/<skill-name>/:

.claude/skills/
└── my-custom-skill/
    ├── SKILL.md              # Required: instructions + frontmatter
    ├── references/           # Optional: supplementary docs Claude loads on demand
    │   ├── workflow-steps.md
    │   └── output-standards.md
    └── scripts/              # Optional: executable scripts the skill invokes
        └── generate-report.py

The SKILL.md Format

The SKILL.md file has two parts: YAML frontmatter and markdown instructions.

Frontmatter Fields

---
name: gk:my-skill          # Required: unique identifier (lowercase, hyphens)
description: "Clear description of what this skill does and WHEN Claude should use it."
version: 1.0.0             # Optional but recommended
argument-hint: "[arg1] [--flag]"  # Optional: shown in autocomplete
license: MIT               # Optional
---

The name field determines the activation command — gk:my-skill activates as /gk:my-skill. The description is especially important: Claude uses it to decide whether to auto-activate the skill when it detects a relevant task.

Instructions Body

The markdown below the frontmatter contains everything Claude follows when the skill is active:

# My Skill Name

Brief one-line summary of what this skill does.

## When to Use
- List the specific situations that should trigger this skill
- Be concrete — vague conditions cause missed activations

## Workflow

1. Step one with exact instructions
2. Step two referencing a reference file if needed
   Load: `references/workflow-steps.md`

## Output Requirements
- What files to create
- Where to save reports
- What format results should take

## Examples
```
/my-skill "example task description"
```

Using Reference Files

For complex skills, split detailed instructions across reference files that the skill loads on demand. This keeps SKILL.md concise while still providing depth when needed:

## Core Workflow

### 1. Analysis Phase
Load: `references/analysis-workflow.md`
**Skip if:** Fast mode is active

### 2. Output Generation
Load: `references/output-standards.md`

Reference files use plain markdown. Claude reads them when the skill instructs it to — they are not loaded automatically, which keeps token usage efficient.

Including Scripts

Place executable scripts in scripts/. The skill instructions tell Claude how to invoke them using the project’s venv Python interpreter:

## Report Generation

Run the report script after analysis completes:

```bash
.claude/skills/.venv/bin/python3 .claude/skills/my-skill/scripts/generate-report.py \
  --input "$ANALYSIS_OUTPUT" \
  --output "$REPORTS_PATH"
```

Practical Example: A Changelog Skill

Here is a complete minimal skill that generates a changelog entry from recent git commits:

---
name: gk:changelog
description: "Generate a changelog entry from recent git commits. Use when the user asks to update the changelog, document changes, or prepare release notes."
version: 1.0.0
argument-hint: "[version] [--since=SHA]"
---

# Changelog Generator

Generates formatted changelog entries from git history.

## When to Use
- User asks to update CHANGELOG.md
- After completing a feature or fix cycle
- When preparing a release

## Workflow

1. Get recent commits since last tag:
   `git log $(git describe --tags --abbrev=0)..HEAD --oneline`

2. Group commits by type (feat, fix, chore, docs)

3. Write entry following Keep a Changelog format:
   ```markdown
   ## [version] - YYYY-MM-DD
   ### Added
   - feature description
   ### Fixed
   - bug fix description
   ```

4. Append to CHANGELOG.md above previous entry

## Output
- Updated CHANGELOG.md in project root
- Summary of changes added

Registering the Skill

No registration step is needed. Claude Code scans .claude/skills/ at session start and makes all discovered skills available. The new skill activates immediately with /gk:changelog.

Next Steps