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

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

If the repo already exists, pull the latest:

cd $HERMES_HOME/skill-tracker
git pull

Step 2: Install the plugin

Copy the plugin code and scripts from the cloned repo:

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:

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:

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:

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:

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:

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:

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:

# 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:

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:

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)