# numencore-toolkit

Personal Claude Code plugin marketplace. Self-hosted on Forgejo.

## Install

```bash
git clone ssh://git@git.numencore.com:2222/phatch/numencore-toolkit.git
claude plugin marketplace add ~/numencore-toolkit
claude plugin install numencore-core@numencore-toolkit
claude plugin install git-tools@numencore-toolkit
```

Verify with `claude plugin list` or `/reload-plugins` in an active session.

## Plugin management

```bash
# List installed
claude plugin list

# Update marketplace (re-reads from disk)
claude plugin marketplace update numencore-toolkit

# Reinstall after editing skills (re-caches)
claude plugin install <plugin>@numencore-toolkit

# Disable/enable
claude plugin disable <plugin>@numencore-toolkit
claude plugin enable <plugin>@numencore-toolkit

# Uninstall
claude plugin uninstall <plugin>@numencore-toolkit
```

## Development

### Structure

```
plugins/<plugin-name>/
├── .claude-plugin/plugin.json
└── skills/<skill-name>/SKILL.md
```

### Cache and skill registration

Claude Code caches plugin contents at install time under `~/.claude/plugins/cache/`. The harness loads skills from the cache at startup, not from the source directory. This means:

- **Adding or editing a skill requires re-caching.** The source files on disk are not read at runtime.
- **`claude plugin update` compares version strings**, not file contents. If `plugin.json` still has the same version, `update` reports "already at latest" and the cache stays stale.

To refresh the cache after adding or changing skills:

```bash
# Option A: bump version in plugin.json, then update
claude plugin update <plugin>@numencore-toolkit

# Option B: force re-cache via reinstall (no version bump needed)
claude plugin uninstall <plugin>@numencore-toolkit
claude plugin install <plugin>@numencore-toolkit
```

After re-caching, **restart Claude Code** — the harness loads skills at startup.

For faster iteration during development, bypass the cache entirely:

```bash
claude --plugin-dir ~/numencore-toolkit/plugins/<plugin-name>
```

### Permissions whitelist

Each skill needs a permission entry in `.claude/settings.local.json` to run without manual approval:

```
"Skill(<plugin-name>:<skill-name>)"
```

Add this when creating a new skill.

### Adding a new skill to an existing plugin

1. Create `plugins/<plugin>/skills/<skill-name>/SKILL.md`
2. Add `Skill(<plugin>:<skill-name>)` to `.claude/settings.local.json`
3. Re-cache: `claude plugin uninstall <plugin>@numencore-toolkit && claude plugin install <plugin>@numencore-toolkit`
4. Restart Claude Code

### Adding a new plugin

1. Create `plugins/<name>/.claude-plugin/plugin.json`
2. Add skills under `plugins/<name>/skills/<skill-name>/SKILL.md`
3. Register in `.claude-plugin/marketplace.json`
4. Add `Skill(<name>:<skill-name>)` entries to `.claude/settings.local.json`
5. Run `claude plugin marketplace update numencore-toolkit`
6. Run `claude plugin install <name>@numencore-toolkit`

## Plugins

| Plugin | Description |
|--------|-------------|
| `numencore-core` | Core toolkit — skill authoring, project scaffolding |
| `git-tools` | Git workflow — commit formatting, branch management |