Agent skill

V5 Migration

by OpenLitterMap in OpenLitterMap/openlittermap-web

The olm:v5 migration script, UpdateTagsService, batch processing, migratedat, ClassifyTagsService deprecated mappings, and data migration from v4 category tables.

GPL-3.0Auto-check passedDatabases

Install V5 Migration

skills CLI
$ npx skills add OpenLitterMap/openlittermap-web --skill v5-migration -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install OpenLitterMap/openlittermap-web v5-migration --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/OpenLitterMap/openlittermap-web.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.ai/skills/v5-migration .claude/skills/v5-migration && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
v5-migration
GitHub stars
134
Token cost
~1.7k tokens
SKILL.md length
388 words
Files
1
Skills in repo
16
Repo updated
First seen
Licence
GPL-3.0

At a glance

The olm:v5 migration script, UpdateTagsService, batch processing, migratedat, ClassifyTagsService deprecated mappings, and data migration from v4 category tables.

  • Works in 5 steps: migrated_at prevents reprocessing. Once… → Migration is per-user, batched. Default… → Three-step per photo:… → …
  • Tasks that involve Database migrations
  • SKILL.md covers Key Files, Invariants, Patterns and Post-Migration Fix: Orphaned…, plus 1 more section
  • Calls php

What it does

V5 Migration is an agent skill from OpenLitterMap/openlittermap-web. The olm:v5 migration script, UpdateTagsService, batch processing, migratedat, ClassifyTagsService deprecated mappings, and data migration from v4 category tables.

Its SKILL.md is about 1.7k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Databases, covering Database migrations and Data pipelines and ETL. It works with PHP and Laravel. The repository describes itself as: https://opengeospatialdata.springeropen.com/articles/10.1186/s40965-018-0050-y. The licence is GPL-3.0.

When your agent uses it

  • Tasks that involve Database migrations
  • Tasks that involve Data pipelines and ETL

Example prompts

  • “/v5-migration”

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

  1. migrated_at prevents reprocessing. Once set, the photo is skipped on subsequent runs. Re-running processes 0 photos.
  2. Migration is per-user, batched. Default 500 photos per batch. Memory managed with gc_collect_cycles() between users.
  3. Three-step per photo: UpdateTagsService::updateTags() -> GeneratePhotoSummaryService::run() -> MetricsService::processPhoto() -> mark…
  4. Errors are logged and skipped. A failed photo doesn't halt the migration. The next run retries it (no migrated_at set).
  5. Seeds reference tables if empty. Categories, brands, achievements seeded on first run.

What it can do on your machine

Read from SKILL.md and the folder at commit ac688aa. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • php

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

V5 Migration loads about 1.7k tokens when it runs. Until then it costs about 44 tokens; SKILL.md has 388 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~44
When it runs · the whole SKILL.md, loaded when a task matches
~1.7k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from OpenLitterMap/openlittermap-web at commit ac688aa, republished under its GPL-3.0 licence (© OpenLitterMap). 388 words, ~1,683 tokens.

Download SKILL.mdSave it as .claude/skills/v5-migration/SKILL.md (or your agent's skills folder).
name
v5-migration
description
The olm:v5 migration script, UpdateTagsService, batch processing, migrated_at, ClassifyTagsService deprecated mappings, and data migration from v4 category tables.

V5 Migration

php artisan olm:v5 migrates photos from v4 category-based tags (14 separate tables like smoking, food, coffee) to v5 normalized PhotoTags. Processes per-user, in batches, with idempotency via migrated_at.

Key Files

  • app/Console/Commands/tmp/v5/Migration/MigrationScript.php — Artisan command
  • app/Services/Tags/UpdateTagsService.php — Per-photo v4->v5 conversion
  • app/Services/Tags/ClassifyTagsService.php — Tag classification + deprecated key mapping
  • app/Services/Tags/GeneratePhotoSummaryService.php — Summary JSON + XP after migration
  • app/Services/Achievements/Tags/TagKeyCache.php — Cached tag ID lookups
  • app/Services/Metrics/MetricsService.php — Processes metrics post-migration

Invariants

  1. migrated_at prevents reprocessing. Once set, the photo is skipped on subsequent runs. Re-running processes 0 photos.
  2. Migration is per-user, batched. Default 500 photos per batch. Memory managed with gc_collect_cycles() between users.
  3. Three-step per photo: UpdateTagsService::updateTags() -> GeneratePhotoSummaryService::run() -> MetricsService::processPhoto() -> mark migrated_at.
  4. Errors are logged and skipped. A failed photo doesn't halt the migration. The next run retries it (no migrated_at set).
  5. Seeds reference tables if empty. Categories, brands, achievements seeded on first run.

Patterns

Command usage
bash
php artisan olm:v5                    # All users
php artisan olm:v5 --user=123         # Single user
php artisan olm:v5 --batch=1000       # Custom batch size
php artisan olm:v5 --skip-locations   # Skip location cleanup step
Migration flow per photo
php
// UpdateTagsService::updateTags($photo)
public function updateTags(Photo $photo): void
{
    // 1. Read v4 data from old category relationships
    [$tags, $customTagsOld] = $this->getTags($photo);

    // 2. Classify each tag (handles deprecated key mapping)
    $parsed = $this->parseTags($tags, $customTagsOld, $photo->id);
    // Returns: ['groups' => [...], 'globalBrands' => [...], 'customTags' => [...]]

    // 3. Create v5 PhotoTag + PhotoTagExtraTags records
    $this->createPhotoTags($photo, $parsed);
}
Tag parsing (v4 -> v5 classification)
php
// Input: ['smoking' => ['butts' => 5, 'cigaretteBox' => 1], 'brands' => ['marlboro' => 3]]

// For each tag:
$result = $this->classifyTags->classify($tagKey);
// 1. Check normalizeDeprecatedTag() — maps old keys to new + materials
// 2. Look up Category by key
// 3. Look up LitterObject by key (or auto-create as crowdsourced)
// 4. Return classification with materials list

// Output groups structure:
[
    'groups' => [
        'smoking' => [
            'category_id' => 2,
            'objects' => [
                ['id' => 45, 'key' => 'butts', 'quantity' => 5, 'materials' => ['plastic', 'paper']],
            ]
        ]
    ],
    'globalBrands' => [['id' => 12, 'key' => 'marlboro', 'quantity' => 3]],
    'customTags' => [...]
]
TagKeyCache preloading
php
// Called once at script startup for performance
TagKeyCache::preloadAll();

// Three-layer cache: in-memory array -> Redis hash (24h TTL) -> database
$id = TagKeyCache::idFor('material', 'glass');         // fast lookup
$id = TagKeyCache::getOrCreateId('material', 'glass'); // upsert if missing
Memory management
php
// In migration loop:
DB::disableQueryLog();           // Prevent query log from growing
gc_collect_cycles();             // Between users
// Batch stats: time, speed (photos/sec), memory delta per batch
MigrationScript command structure
php
protected $signature = 'olm:v5
    {--skip-locations : Skip the locations cleanup step}
    {--user= : Specific user ID to migrate}
    {--batch=500 : Number of photos per batch}';

public function handle(): int
{
    $this->ensureProcessingColumns();  // Add processed_* if missing
    $this->seedReferenceTables();      // Categories, brands, achievements
    TagKeyCache::preloadAll();
    DB::disableQueryLog();
    $this->runMigration();             // Per-user, batched
}

Post-Migration Fix: Orphaned Tags (2026-04-04)

The v5 migration left 189,518 photo_tags rows with category_litter_object_id = NULL because DEPRECATED_TAG_MAP mapped v4 keys to composite names (e.g. beerCan → beer_can) instead of decomposing into object + type (e.g. alcohol.can + type beer). The fallback created runtime litter_objects (crowdsourced=1) without CLO relationships.

Fix commands:

  • php artisan olm:fix-orphaned-tags — Remaps 71 orphan LOs to canonical CLO/LO/type targets. 74 mapping entries (3 multi-category splits). Batched, transacted, idempotent. Supports --apply, --verify-only, --log.
  • php artisan olm:regenerate-summaries --orphan-fix — Regenerates stale summaries for affected photos. Chunked via chunkById, resumable (skips photos with non-null clo_id in summary), Photo::withoutEvents().
  • php artisan olm:reprocess-metrics --from-file=<ids> — Delta-based MetricsService reprocess for ~1,041 photos with XP changes (special object bonus corrections).

Key files:

  • app/Console/Commands/tmp/v5/Migration/FixOrphanedTags.php
  • app/Console/Commands/tmp/v5/Migration/RegenerateSummaries.php
  • app/Console/Commands/tmp/v5/Migration/ReprocessPhotoMetrics.php
  • readme/TagsCleanupPostMigration.md — Full mapping tables and judgment calls
  • readme/changelog/production-orphan-fix-runbook.md — Production execution steps
Show full SKILL.md (106 more words)Show less

Common Mistakes

  • Removing migrated_at check. This is the idempotency guard. Without it, photos get double-migrated.
  • Running without TagKeyCache::preloadAll(). Cold lookups hit the database per tag. Preload caches first.
  • Not calling GeneratePhotoSummaryService after tag creation. Summary must be generated for MetricsService to read.
  • Assuming all v4 keys map 1:1 to v5. Many v4 keys like beerBottle split into object + materials. normalizeDeprecatedTag() handles this.
  • Not handling deprecated category keys. ClassifyTagsService::CATEGORY_ALIASES resolves old category keys: coastal→marine, trashdog→pets, dogshit→pets, automobile→vehicles, pathway→unclassified, drugs→unclassified, political→unclassified, stationery→unclassified. The public getCategory(string $rawKey) method checks aliases before DB lookup.
  • Processing brands inline. Brands are deferred to globalBrands array — not attached to specific objects during migration.

© OpenLitterMap, GPL-3.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in .ai/skills/v5-migration of OpenLitterMap/openlittermap-web.

Open the folder on GitHubat commit ac688aa

Compare with similar skills

V5 Migration next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

V5 Migration compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
V5 Migration this skillOpenLitterMap/openlittermap-web134—~1.7kAutomated safety check: PassGPL-3.0
Data Migrationrevfactory/harness-1001.3k—~1.8kAutomated safety check: PassApache-2.0
MigrationJaguarJack/catch-admin935—~474Automated safety check: PassApache-2.0
Migratesoftspark/ai-toolkit179—~1.3kAutomated safety check: NotesApache-2.0
Configuring Horizoncoollabsio/coolify63k4 repos~898Automated safety check: PassMIT
Geoflowyaojingang/GEOFlow3.8k—~722Automated safety check: PassAGPL-3.0

Similar skills

  • Data Migration

    revfactory/harness-100

    Full migration pipeline where an agent team collaborates to perform source analysis, schema mapping, transformation script generation, validation query design, and rollback planning.

    1.3k GitHub stars~1.8k tokensUpdated 6 mo ago
    DatabasesAuto-check passed
  • Migration

    JaguarJack/catch-admin

    Generate database migration file for CatchAdmin module. An agent skill from JaguarJack/catch-admin.

    935 GitHub stars~474 tokensUpdated 21 days ago
    DatabasesAuto-check passed
  • Migrate

    softspark/ai-toolkit

    Run/create DB migrations (Alembic, Prisma, Laravel, Django, Flyway, Drizzle); checks backup.

    179 GitHub stars~1.3k tokensUpdated today
    DatabasesAuto-check: notes
  • Configuring Horizon

    coollabsio/coolify

    A skill your agent uses whenever the user mentions Horizon by name in a Laravel context.

    63k GitHub starsUsed in 4 repos~898 tokens
    Backend & APIsAuto-check passed
  • Geoflow

    yaojingang/GEOFlow

    Operate/develop GEOFlow CLI/Laravel/admin/API, topics/专题 and topic tasks, theme libraries/replication, sites/leads/Agent, channel sync and legacy yao-geoflow-cli/design/template migration.

    3.8k GitHub stars~722 tokensUpdated 6 days ago
    Backend & APIsAuto-check passed
  • Analyzing Data

    astronomer/agents

    Queries the data warehouse with SQL and answers business questions about data.

    450 GitHub stars~1.3k tokensUpdated 2 days ago
    DatabasesAuto-check passed

More from OpenLitterMap/openlittermap-web

All 16 skills in this repo
  • Tailwindcss Development

    OpenLitterMap/openlittermap-web

    Styles applications using Tailwind CSS v3 utilities. An agent skill from OpenLitterMap/openlittermap-web.

    134 GitHub stars~713 tokensUpdated 23 days ago
    Auto-check passed
  • Olm Architecture

    OpenLitterMap/openlittermap-web

    OpenLitterMap v5 architecture reference. An agent skill from OpenLitterMap/openlittermap-web.

    134 GitHub stars~5.2k tokensUpdated 23 days ago
    Auto-check passed
  • Achievements System

    OpenLitterMap/openlittermap-web

    AchievementEngine, AchievementRepository, milestone checkers, AchievementsSeeder, userachievements pivot, AchievementsController API, and achievement evaluation flow.

    134 GitHub stars~1.4k tokensUpdated 23 days ago
    Auto-check passed
  • Admin System

    OpenLitterMap/openlittermap-web

    AdminController, photo approval, tag editing, deletion, MetricsService integration, admin middleware, verification queue, and admin XP.

    134 GitHub stars~3.9k tokensUpdated 23 days ago
    Auto-check passed
  • API Endpoints

    OpenLitterMap/openlittermap-web

    REST API endpoints, route structure, auth guards, request/response contracts, error patterns, and the full API surface for web SPA and mobile clients.

    134 GitHub stars~4k tokensUpdated 23 days ago
    Auto-check passed
  • Clustering System

    OpenLitterMap/openlittermap-web

    ClusteringService, tile keys, dirty tiles/teams, clustering commands, ClusterController GeoJSON API, PhotoObserver dirty marking, and map cluster rendering.

    134 GitHub stars~2k tokensUpdated 23 days ago
    Auto-check passed

Works with

Questions about V5 Migration

What does V5 Migration do?

The olm:v5 migration script, UpdateTagsService, batch processing, migratedat, ClassifyTagsService deprecated mappings, and data migration from v4 category tables. V5 Migration is an agent skill from OpenLitterMap/openlittermap-web. The olm:v5 migration script, UpdateTagsService, batch processing, migratedat, ClassifyTagsService deprecated mappings, and data migration from v4 category tables.

When should I use V5 Migration?

V5 Migration fits situations like: tasks that involve Database migrations; tasks that involve Data pipelines and ETL.

How do I install V5 Migration in Claude Code?

Run `npx skills add OpenLitterMap/openlittermap-web --skill v5-migration -a claude-code`. Or copy the skill folder (.ai/skills/v5-migration in OpenLitterMap/openlittermap-web) into .claude/skills/v5-migration in your project. Claude Code loads it when a task matches its description.

How do I install V5 Migration in Codex?

Run `npx skills add OpenLitterMap/openlittermap-web --skill v5-migration -a codex`. Or copy the skill folder (.ai/skills/v5-migration in OpenLitterMap/openlittermap-web) into .agents/skills/v5-migration in your project. Codex loads it when a task matches its description.

Can I use V5 Migration in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add OpenLitterMap/openlittermap-web --skill v5-migration -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/v5-migration, .gemini/skills/v5-migration, .github/skills/v5-migration and .opencode/skills/v5-migration in your project.

What does V5 Migration need to run?

Going by SKILL.md and its folder, V5 Migration needs the command-line tools its instructions call (php).

Does V5 Migration access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is V5 Migration safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does V5 Migration use?

V5 Migration is published under the GPL-3.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does V5 Migration use?

About 1.7k tokens (SKILL.md is roughly 6.7k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to V5 Migration?

Skills that share tags, products or a category with V5 Migration: Data Migration (revfactory/harness-100, 1.3k stars), Migration (JaguarJack/catch-admin, 935 stars), Migrate (softspark/ai-toolkit, 179 stars) and Configuring Horizon (coollabsio/coolify, 63k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains V5 Migration?

OpenLitterMap (a GitHub organization) maintains it in OpenLitterMap/openlittermap-web, which has 134 GitHub stars. The repository holds 16 skills in this directory. The repository was last updated on September 14, 2026.

Source: OpenLitterMap/openlittermap-web on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.