How to Reuse Context with Skills

How to Reuse Context with Skills#

Every new gptme session starts blank. If your project has conventions (a naming scheme, a non-obvious architecture decision, a required step before running tests), you end up pasting the same explanation repeatedly — or getting wrong first drafts because the agent lacked context.

A skill is a plain markdown document (SKILL.md) that gptme injects into the session context when its name is requested. Write the explanation once, commit it, and gptme makes it available on demand. Use this guide to create a skill and to compose skills into multi-step workflows.

Create a skill#

Skills live in named subdirectories under skills/ at your project root, or under ~/.config/gptme/skills/ for user-global skills. For example, a skill for your project’s database migration convention:

mkdir -p skills/db-migration
cat > skills/db-migration/SKILL.md << 'EOF'
---
name: db-migration
description: Django migration conventions and pre-migration checklist
---

# Migration Workflow

## Before creating a migration

1. Run `make lint` — schema changes that fail lint cause corrupt migrations.
2. Squash pending migrations if there are more than 10.
3. Never create a migration on an unmerged feature branch.

## Creating a migration

```bash
python manage.py makemigrations --name describe_the_change
```

## Reverting a migration

```bash
python manage.py migrate myapp 0042  # the migration before yours
```
EOF

gptme discovers skills in the project’s skills/ directory automatically — no configuration needed.

Use a skill#

Skills are loaded by name. Request one explicitly in your prompt:

gptme "Using the db-migration skill, help me add a nullable email field to the User model"

Compose skills into a workflow#

Real workflows are multi-step: run tests, update a changelog, create a tag, push. A single monolithic prompt for this is brittle — it’s hard to update one step without breaking others, and you can’t reuse the steps elsewhere.

Instead, keep detailed conventions in focused sub-skills and sequence them in a workflow skill. Three focused sub-skills, each in its own SKILL.md:

# skills/release-check-tests/SKILL.md
---
name: release-check-tests
description: Verify the test suite passes before any release action
---
# Check Tests Before Release

Always run the full test suite before any release action:

    make test

If any test fails, STOP and fix it before proceeding.

# skills/release-update-changelog/SKILL.md
---
name: release-update-changelog
description: Changelog update convention for releases
---
# Changelog Update Convention

Format: `## [X.Y.Z] - YYYY-MM-DD` with sections Added / Changed / Fixed / Removed.
Always add the new version block at the TOP of CHANGELOG.md, above previous versions.
Never delete old entries.

# skills/release-tag-and-push/SKILL.md
---
name: release-tag-and-push
description: Git tagging and push convention for releases
---
# Tag and Push Convention

Create an annotated tag:

    git tag -a v$VERSION -m "Release v$VERSION" && git push origin master --tags

Do not push without a passing CI run on master.

A workflow skill that chains all three:

# skills/release-workflow/SKILL.md
---
name: release-workflow
description: Full release pipeline — test, changelog, tag, push
---
# Release Workflow

Steps in order:
1. Run `make test` (stop on failure)
2. Update CHANGELOG.md with the new version
3. Commit the changelog: `git commit CHANGELOG.md -m "chore: update changelog for vX.Y.Z"`
4. Create the annotated tag and push: `git tag -a v$VERSION -m "Release v$VERSION" && git push origin master --tags`

Name the workflow and every sub-skill you want loaded — mentioning the workflow alone does not recursively load the skills it references:

gptme "Using the release-workflow, release-check-tests, release-update-changelog, and release-tag-and-push skills, do a release for v1.4.2"

Tips#

  • Keep sub-skills short: under ~50 lines each. Long skills dilute focus; split them.

  • Commit skills to the repo so all contributors benefit, and use git log skills/ to audit how your workflows evolved.

  • Write once, use everywhere: skills also work in other runtimes, such as Claude Code with the hook adapter.

  • See Skills for the full skill format reference, and Lessons for guidance that is injected automatically by keyword instead of by name.

Contents