@globalfishingwatch/skills

Agent skills for GFW applications, shareable across repos. Each skill lives in src/<skill-name>/: a SKILL.md (instructions for the agent), runnable scripts, reference docs, and its own code — built into its own self-contained bundle so the whole dist/<skill-name>/ folder can be copied anywhere and just works.

Prerequisites: Node 24 (see .nvmrc at the repo root) and pnpm (see packageManager in the root package.json). Skill scripts themselves run on Node >= 24 (module.registerHooks).

This package is not consumed by apps in this monorepo. It lives here so the bundles can reuse platform config and @globalfishingwatch/* libraries.

Skills

• encode-url — build a platform URL + TanStack Router navigation config from a navigation intent (route, layers, filters, time range, viewport).
• decode-url — decode a platform URL into structured context of what the user is seeing.

Both use the real parseWorkspace/stringifyWorkspace from @globalfishingwatch/dataviews-client, so URLs match the app byte-for-byte. encode-url owns the shared logic (layer dictionary, route matching) and decode-url imports it from there.

Install a skill

Copy the built skill folder into the agent's skills directory. Prefer the published npm package — no monorepo clone, no workspace install.

From npm

pnpm add @globalfishingwatch/skills
cp -r node_modules/@globalfishingwatch/skills/dist/encode-url ~/.claude/skills/
cp -r node_modules/@globalfishingwatch/skills/dist/decode-url ~/.claude/skills/

Into gfw-agent

Its skills live at repo root skills/<skill-name>/ (not .claude/skills/), and each agent profile (agents/<name>.json) opts in via a skills array:

pnpm add @globalfishingwatch/skills
cp -r node_modules/@globalfishingwatch/skills/dist/encode-url skills/
cp -r node_modules/@globalfishingwatch/skills/dist/decode-url skills/

Then add the skill name(s) to the profile, e.g. agents/default.json:

"skills": ["encode-url", "decode-url"]

From this monorepo

pnpm nx build skills

# Claude Code, this project only
cp -r libs/skills/dist/encode-url .claude/skills/

# Claude Code, all your projects
cp -r libs/skills/dist/decode-url ~/.claude/skills/

Or, for your own ~/.claude/skills/, one command per skill — builds, wipes the old copy, reinstalls:

pnpm nx run skills:claude:encode-url
pnpm nx run skills:claude:decode-url

Programmatic use

import { decodeMapUrl } from '@globalfishingwatch/skills/decode-url'
import { encodeMapUrl } from '@globalfishingwatch/skills/encode-url'

const context = decodeMapUrl(currentUrl)
const { navigation, path } = encodeMapUrl({ route: { type: 'workspace' }, state: context.raw })

@globalfishingwatch/skills (no subpath) also re-exports both, for convenience.

No .d.ts is published — esbuild can't emit them, and a plain tsc emit would leak imports of @globalfishingwatch/dataviews-client and the private @platform/config into the output.

Development

pnpm nx build skills

This produces libs/skills/dist/: a combined index.js, plus one self-contained folder per skill (encode-url/, decode-url/) — each with its own index.js bundle alongside SKILL.md, scripts/, and references/.

Skill scripts run with plain node (>= 24) and import their own skill's bundle as @globalfishingwatch/skills/<skill-name>, resolved by scripts/register-gfw-resolver.mjs from (in order): a sibling index.js (dist output), a ../../dist/<skill-name>/index.js in this monorepo (unbuilt source layout), or — once installed as an npm package — normal node_modules resolution via the package's exports map.

Adding a new skill

Create libs/skills/src/<skill-name>/ with SKILL.md (+ optional scripts/, references/, and code). If it needs logic another skill already has (e.g. the layer dictionary or route matching in encode-url/), import it from there rather than duplicating it. Export the skill's public API from an index.ts, add its path to src/index.ts, and:

• add it as an additionalEntryPoints entry + exports["./<skill-name>"] in package.json, so it gets its own bundle
• add its assets globs (SKILL.md, scripts/**/*, references/**/*, …) to the build target in project.json