# Skill Tracker Setup

> Install and configure the skill-tracker plugin. Clone the repo, install the plugin, configure tracked repos, create cron jobs, and verify setup. Safe to re-run for updates.

- Skill: `cnuahs/skill-tracker-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cnuahs/skill-tracker-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cnuahs/skill-tracker-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: cnuahs (https://skillmd.com/u/cnuahs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cnuahs/skill-tracker-setup

---


# skill-tracker Setup

## Overview

This skill installs and configures the skill-tracker plugin from GitHub. It guides the user through the full setup: cloning the repo, installing the plugin, configuring tracked repos, creating cron jobs, and verifying everything works.

**This skill is safe to re-run.** Each step checks what already exists and skips or merges as appropriate. Re-running is the way to add repos, change the token, update cron settings, or refresh the plugin after a repo update.

**How the user triggers this skill:**

1. User installs the setup skill from GitHub:
   ```
   hermes skills install cnuahs/skill-tracker/skills/skill-tracker-setup
   ```
2. User tells the agent: "set up skill-tracker", "install the skill tracker plugin", "add a repo to skill-tracker", "update skill-tracker config", or similar
3. The agent finds `skill-tracker-setup` in the skills list, loads this SKILL.md, and follows the procedure below.

**End state after setup:**
- Plugin + scripts installed at `$HERMES_HOME/plugins/skill-tracker/`
- Cron skills installed at `$HERMES_HOME/skills/skill-tracker/` (skill-tracker-push-pr, skill-tracker-rebase)
- Plugin registered in `$HERMES_HOME/config.yaml` under `plugins.enabled`
- `skill_tracker` config section written with repos, agent name, and token
- skill-tracker-push-pr cron and skill-tracker-rebase cron created and enabled
- Gateway restarted and plugin loaded

## When to Use

- First-time setup: "set up skill-tracker" or "install the skill tracker plugin"
- Add a repo: "add a repo to skill-tracker" or "track another repo"
- Change config: "update skill-tracker config" or "change the token for skill-tracker"
- Update plugin: "update skill-tracker" (pulls latest from GitHub and reinstalls)
- Fix cron jobs: "recreate skill-tracker cron jobs"

## Prerequisites

- Hermes gateway running
- `gh` CLI authenticated with GitHub, OR a GitHub personal access token available
- `git` available on PATH (bundled with Hermes)
- `$HERMES_HOME` environment variable set (standard Hermes requirement)
- Python 3.10+ available (for plugin scripts)

## Workflow

### Step 1: Clone the skill-tracker repo

```bash
cd $HERMES_HOME
git clone https://github.com/cnuahs/skill-tracker.git
```

If the repo already exists, pull the latest:

```bash
cd $HERMES_HOME/skill-tracker
git pull
```

### Step 2: Install the plugin

Copy the plugin code and scripts from the cloned repo:

```bash
cp -r $HERMES_HOME/skill-tracker/plugin $HERMES_HOME/plugins/skill-tracker
cp -r $HERMES_HOME/skill-tracker/scripts $HERMES_HOME/plugins/skill-tracker/scripts
```

Verify:

```bash
ls $HERMES_HOME/plugins/skill-tracker/
# Expected: __init__.py  gitutils.py  commitmsg.py  gh_api.py  queries.py  plugin.yaml  scripts/
ls $HERMES_HOME/plugins/skill-tracker/scripts/
# Expected: collect.py  fetch.py  group.py  plan_rebase.py  push.py  rebase.py
```

### Step 2a: Install cron skills

The skill-tracker-push-pr and skill-tracker-rebase cron jobs reference skills in `$HERMES_HOME/skills/skill-tracker/`. Copy them from the cloned repo:

```bash
mkdir -p $HERMES_HOME/skills/skill-tracker
cp -r $HERMES_HOME/skill-tracker/skills/skill-tracker-push-pr $HERMES_HOME/skills/skill-tracker/skill-tracker-push-pr
cp -r $HERMES_HOME/skill-tracker/skills/skill-tracker-rebase $HERMES_HOME/skills/skill-tracker/skill-tracker-rebase
```

Verify:

```bash
ls $HERMES_HOME/skills/skill-tracker/
# Expected: skill-tracker-push-pr/  skill-tracker-rebase/
```

### Step 3: Register the plugin

Add `skill-tracker` to `plugins.enabled` in `$HERMES_HOME/config.yaml`.

First, create a backup:

```bash
cp $HERMES_HOME/config.yaml $HERMES_HOME/config.yaml.bak.$(date +%Y%m%d-%H%M%S)
```

Then read config.yaml and determine what needs to change:

- If `plugins.enabled` list exists and already contains `- skill-tracker`, skip
- If `plugins.enabled` list exists but doesn't contain it, append `- skill-tracker`
- If `plugins` section doesn't exist, add the full block

Use `patch` (find-and-replace) to make targeted edits. Do NOT replace the entire file.

After editing, validate:

```bash
python3 -c "import yaml; yaml.safe_load(open('$HERMES_HOME/config.yaml'))" && echo "VALID" || echo "INVALID"
```

If INVALID, restore from backup and report the error to the user:

```bash
cp $HERMES_HOME/config.yaml.bak.<timestamp> $HERMES_HOME/config.yaml
```

### Step 4: Configure tracked repos

Read the current `skill_tracker` section from config.yaml if it exists. Present the current config to the user and ask what they want to change:

- **Add a repo** — ask for path, then optional URL and main branch
- **Remove a repo** — show current repos, ask which to remove
- **Change agent name** — ask for new name
- **Change token env var** — ask for new env var name
- **Replace everything** — re-enter all config from scratch
- **No changes** — skip to Step 5

If the `skill_tracker` section does not exist, create it from scratch (same flow as above but all fields are new).

For adding repos, discover what's available to help the user:

```bash
# Standard Hermes skill dir
ls $HERMES_HOME/skills/ 2>/dev/null && echo "  (exists)" || echo "  (not found)"

# External dirs from config
python3 -c "
import yaml
cfg = yaml.safe_load(open('$HERMES_HOME/config.yaml'))
for d in cfg.get('skills', {}).get('external_dirs', []):
    import os; print(d, '(exists)' if os.path.isdir(d) else '(not found)')
"
```

For each repo, ask:
- Remote URL (optional — defaults to the repo's `origin` remote)
- Main branch name (optional — defaults to `main`)

Construct the YAML snippet and use `patch` to insert or replace the `skill_tracker` section. Then validate:

```bash
python3 -c "import yaml; yaml.safe_load(open('$HERMES_HOME/config.yaml'))" && echo "VALID" || echo "INVALID"
```

If INVALID, restore from the backup created in Step 3:

```bash
cp $HERMES_HOME/config.yaml.bak.<timestamp> $HERMES_HOME/config.yaml
```

### Step 5: Create cron jobs

List existing cron jobs:

```
hermes cron list
```

For each expected cron job (skill-tracker-push-pr and skill-tracker-rebase),
check if a job with a matching name already exists. If it does, ask the user
whether to update it. If yes, update in-place using the job's `job_id`:

```
cronjob(action='update', job_id=<id>, name=..., prompt=..., schedule=..., ...)
```

If no matching job exists, create a new one:

```
cronjob(action='create', name=..., prompt=..., schedule=..., ...)
```

Before creating new cron jobs, ask the user: "Where would you like cron
output delivered? You can choose local delivery, or specify a messaging
platform and channel/chat ID (e.g. `slack:C01234567890`, `discord:123456789`,
`telegram:-1001234567890`)."

#### skill-tracker-push-pr cron (every 6 hours)

Prompt:
```
Read and follow the skill-tracker-push-pr skill at $HERMES_HOME/skills/skill-tracker/skill-tracker-push-pr/SKILL.md. Execute the push+PR workflow for all configured repos.

[IMPORTANT: You are running as a scheduled cron job. DELIVERY: Your final response will be automatically delivered to the user — do NOT use send_message or try to deliver the output yourself. Just produce your report/output as your final response and the system handles the rest. SILENT: If there is genuinely nothing new to report, respond with exactly "[SILENT]" (nothing else) to suppress delivery. Never combine [SILENT] with content — either report your findings normally, or say [SILENT] and nothing more.]
```

Create with:
- Name: `skill-tracker-push-pr`
- Schedule: `every 360m`
- Delivery: `<user's choice>` (e.g. `local`, `slack:<channel>`, `discord:<channel>`, `telegram:<chat_id>`)
- Enabled: true
- Toolsets: `terminal`, `file`

#### skill-tracker-rebase cron (daily at 8pm)

Prompt:
```
Read and follow the skill-tracker-rebase skill at $HERMES_HOME/skills/skill-tracker/skill-tracker-rebase/SKILL.md. Execute the rebase workflow for all configured repos.

[IMPORTANT: You are running as a scheduled cron job. DELIVERY: Your final response will be automatically delivered to the user — do NOT use send_message or try to deliver the output yourself. Just produce your report/output as your final response and the system handles the rest. SILENT: If there is genuinely nothing new to report, respond with exactly "[SILENT]" (nothing else) to suppress delivery. Never combine [SILENT] with content — either report your findings normally, or say [SILENT] and nothing more.]
```

Create with:
- Name: `skill-tracker-rebase`
- Schedule: `0 20 * * *`
- Delivery: same as push-pr cron
- Enabled: true
- Skills: `skill-tracker-rebase` (loaded before prompt runs)

### Step 6: Restart the gateway

Tell the user:

> "Setup is complete. Please restart the gateway to load the plugin:
>
> ```
> hermes gateway restart
> ```
>
> After restart, the plugin will be loaded and the cron jobs will begin on schedule."

Do NOT restart the gateway yourself. The user must do this manually.

### Step 7: Verify (after user restarts)

After the user confirms the gateway has restarted, verify:

1. **Cron jobs active** — run `hermes cron list` and confirm skill-tracker-push-pr and skill-tracker-rebase show `enabled: true`
2. **Test commit** — make a trivial `skill_manage` call (e.g., `skill_manage(action="patch", name="<any-tracked-skill>", file_path="SKILL.md", old_string="foo", new_string="foo")`) and verify a commit appears on the agent branch in the tracked repo

If the test commit doesn't appear, check:
- Is the skill in a registered repo? (check `skill_tracker.repos` in config.yaml)
- Is the agent branch created? (`git branch -a` in the repo)
- Is the plugin loaded? (check `plugins.enabled` in config.yaml contains `skill-tracker`)

## Common Pitfalls

### Token not available in plugin process
The plugin reads the token from `os.environ[token_env]` for remote operations (push, fetch, PR creation). Local commits work without a token. If remote operations fail, ensure the token is available in the gateway process environment (e.g., in `$HERMES_HOME/.env`, or however you configure environment variables for your gateway process).

### Repo not in Hermes search path
The plugin only tracks repos that are in Hermes' skill-resolution path (local `skills/` dir or `skills.external_dirs`). If the user wants to track a repo that's not in `external_dirs`, they must add it there first — the plugin won't track repos Hermes can't find skills in.

### Cron delivery failures are silent

If the delivery target (messaging platform + channel/chat ID) is invalid or
the platform is disconnected, the cron job will still run but output will
not be delivered. The agent cannot validate the target at setup time - if
cron output is not appearing, check the delivery target and platform connectivity.

## Files Changed

| File | Change |
|---|---|
| `$HERMES_HOME/skill-tracker/` | Cloned from GitHub |
| `$HERMES_HOME/plugins/skill-tracker/` | Copied from cloned repo (plugin + scripts) |
| `$HERMES_HOME/skills/skill-tracker/` | skill-tracker-push-pr and skill-tracker-rebase skills copied from cloned repo |
| `$HERMES_HOME/config.yaml` | `plugins.enabled` + `skill_tracker` section |
| Cron jobs | skill-tracker-push-pr (every 6h) + skill-tracker-rebase (daily 8pm) |