skillctx

The Problem

Agent skills are personal by default. A skill that posts your standup, manages your todos, or deploys your app is wired to your usernames, paths, Slack channel IDs, and API endpoints. It works perfectly — on your machine.

The moment you share it, it breaks. The next person has to dig through your SKILL.md, find every hardcoded value, and manually swap them out. Multiply that across ten skills and it's no longer "install and use" — it's "install and debug."

For creators, this means your skills aren't truly portable. You can publish them, but every user has to reverse-engineer your personal config.

For users, this means every new skill is a setup chore — hunting through files for values that need changing before anything works.

The Solution

 # SKILL.md (daily-standup)
- Post standup for alice in Slack (CABC123DEF) channel
- Save memo to ~/notes
+ Post standup for {username} in Slack ({channel_id}) channel
+ Save memo to {notebook_path}

Hardcoded values become {placeholders}, resolved at runtime from one shared config (~/.config/skillctx/config.json).

For creators: one command migrates your skill. No manual find-and-replace, no template syntax to learn.

For users: install a skill and run it. On first use you're prompted for missing values — fill them in once and every skill that needs them picks them up automatically. No config files to hunt down, no per-skill setup.

For Skill Creators

One command to migrate. That's it.

npx skills add jackchuka/skillctx   # install skillctx
/skillctx-ify my-skill              # migrate your skill — done

skillctx scans your skill for hardcoded values, replaces them with placeholders, and embeds a tiny zero-dep resolver. Your skill is now portable.

Once in a while, when skillctx itself is updated, one more command propagates changes to all your migrated skills:

/skillctx-sync

How It Works

Phase	What happens	How
1. Scan	Find hardcoded values (usernames, paths, IDs)	Deterministic via scan.py
2. Classify	Decide which values to extract	LLM-assisted judgment
3. Rewrite	Replace values with {placeholders}, embed resolver	Automated

The embedded resolve.py is zero-dep (Python 3.10+ stdlib only) — nothing to install, works anywhere Python runs.

For Skill Users

Zero setup. Install a migrated skill and use it — just like any other skill.

npx skills add creator/my-skill   # install as usual
/my-skill                         # use it — that's it

On first run, the embedded resolver prompts you for any missing values:

> /my-skill

Missing config values for "my-skill":
  username: <your GitHub username>
  notebook_path: <path to your notes directory>

Fill them in once and every skill that needs them picks them up automatically.

Config Format

// ~/.config/skillctx/config.json
{
  "vars": {
    "identity": {
      "github_username": "alice",
      "email": "[email protected]"
    },
    "slack": {
      "standup_channel_id": "CABC123DEF"
    },
    "paths": {
      "notebook": "~/notes"
    }
  },
  "skills": {
    "daily-standup": {
      "username": "vars.identity.github_username",
      "channel_id": "vars.slack.standup_channel_id"
    }
  }
}

vars — shared values organized by category. Write once, reference everywhere.
skills — per-skill bindings. Each key maps to a dotpath in vars.

Architecture

skillctx/
├── skills/
│   ├── skillctx-ify/          # Migration skill
│   │   ├── SKILL.md
│   │   ├── references/
│   │   │   └── known-patterns.md
│   │   └── scripts/
│   │       └── resolve.py     # The embedded resolver (zero-dep)
│   └── skillctx-sync/         # Maintenance skill
│       ├── SKILL.md
│       └── scripts/
│           └── sync.py
├── tests/
│   ├── test_resolve.py
│   └── test_sync.py
├── .github/workflows/
│   └── ci.yml                 # Python 3.10–3.13
└── pyproject.toml

Design Constraints