Skill Maintainer

Use this skill to audit and maintain a ClawHub publisher portfolio, especially when the maintainer needs to identify which skills deserve ongoing public investment.

Operating Principle

Preserve quality first, analyze cleanup second, ask for approval third, execute last.

The default output is an evidence-backed maintenance queue. Prefer skills with real user signal, clear public utility, complete metadata, source provenance, version history, recent updates, and growth momentum. Treat cleanup as secondary and only act on it when the data quality status is ok.

Do not run public visibility changes, merge commands, delete commands, or publish updates unless the user explicitly approves the specific batch or operation.

Core Workflow

1. Refresh portfolio data:

bash python3 scripts/update_all.py --handle <clawhub-handle>

To restart the trend history from a clean baseline while preserving old snapshots in an archive:

bash python3 scripts/update_all.py --handle <clawhub-handle> --baseline

2. Review generated artifacts:

• Dashboard: reports/index.html
• Scored analysis: data/processed/<handle>_skill_analysis.csv
• Summary and quality queue: data/processed/<handle>_summary.json
• Low-signal triage: data/processed/<handle>_low_signal_triage.csv
• Data unavailable queue: data/processed/<handle>_data_unavailable.csv
• Latest snapshot: data/snapshots/<handle>/latest.json
• Growth deltas: data/processed/<handle>_skill_growth.csv
• Trend summary: data/processed/<handle>_trend_summary.json
• General approval board: reports/approval_packets/<handle>_approval_board.md
• Bulk cleanup board: reports/bulk_cleanup/<handle>_bulk_approval_board.md
• AI upgrade plan: reports/auto_upgrade/latest/report.md
• AI maintainer prompts: reports/auto_upgrade/latest/agent_prompts/

3. Explain the recommendation to the user in business terms:

• which skills are worth maintaining first
• which quality signals explain that priority
• what should stay public
• what should be upgraded
• what cleanup was suppressed because the data is partial
• which skills had failed detail fetches and therefore get no decision today
• what should be hidden or merged only after explicit cleanup review
• what should be monitored

4. Ask the user to approve one batch at a time using the exact approval phrase shown in the generated approval board.

5. After approval, execute only the approved commands and report the outcome.

AI Maintenance Candidate Plan

Use scripts/auto_upgrade.py when the portfolio is too large to maintain manually. The loop selects the next high-quality skills worth reviewing, inspects local source packages, writes an evidence report, and creates one prompt per candidate for an AI maintainer. It is a candidate-plan workflow, not an automatic publish workflow.

Plan-only mode:

python3 scripts/auto_upgrade.py --handle <clawhub-handle> --limit 5

Integrated refresh plus plan:

python3 scripts/update_all.py --handle <clawhub-handle> --auto-upgrade-plan --auto-upgrade-limit 5

Fetch missing sources before planning:

python3 scripts/auto_upgrade.py --handle <clawhub-handle> --limit 5 --fetch-source

Missing source lookup order is GitHub first, local roots second, and ClawHub install/download fallback last. If GitHub or ClawHub reports a rate limit, stop instead of retrying and run the source fetch later.

Conservative deterministic edits:

python3 scripts/auto_upgrade.py --handle <clawhub-handle> --limit 5 --apply-safe

--apply-safe is intentionally narrow and must not be used in the daily cron. It only appends missing example prompts or sensitive-domain safety boundaries to local SKILL.md files when the package has no forbidden files and a small file surface. It never publishes, hides, merges, deletes, renames, or changes ownership.

For each generated prompt in reports/auto_upgrade/latest/agent_prompts/, run an AI maintainer with these gates:

• preserve the original public contract and slug
• keep edits small and reviewable
• look for source on GitHub first; if unavailable, use ClawHub install/download as the fallback
• add trigger clarity, examples, workflow, validation checks, tags, bilingual search terms, and safety boundaries where useful
• run validation and dry-run publish before any real publish
• stop on rate limits, auth errors, data-quality warnings, or missing source
• require explicit user approval before publishing

Quality Maintenance Lens

Start with quality_maintenance_queue in data/processed/<handle>_summary.json and reports/action_plans/<handle>_quality_maintenance_plan.csv.

Strong quality signals include:

• installs, stars, comments, or sustained downloads
• public-utility categories such as developer, data, knowledge, automation, or shopping
• rich summary, useful tags, changelog, source repo/path metadata
• multiple versions or recent updates
• positive growth in downloads or installs since the previous snapshot

When a skill has quality signal, recommend concrete upgrades before any visibility cleanup: improve SKILL.md, examples, bilingual search terms, tags, changelog, source metadata, tests, and release notes.

Data Quality Guardrails

Treat the run as partial when profile totals and processed totals diverge, many detail requests fail, many rows are unexpectedly zero-download, the report falls back to cache, or deltas are negative. In partial mode:

• keep quality maintenance, upgrade, and monitor queues
• move failed skill-detail fetches into data_unavailable
• exclude data_unavailable skills from keep, upgrade, hide, merge, delete, monitor, bulk-cleanup, and AI maintenance candidate decisions for that day
• suppress hide, merge, delete, and bulk-cleanup approval batches
• tell the user which warning caused suppression
• refresh data later instead of retrying aggressively during rate limits

Account-Risk Cleanup Lens

When the user says bulk publishing caused an account review, start with scripts/plan_bulk_cleanup.py outputs.

The strongest bulk-risk pattern is:

• low or plausible-low signal
• single version
• zero installs
• zero stars
• zero comments

Recommended default policy:

• Phase 1: hide low-download skills matching the strongest risk pattern only when data quality is ok.
• Phase 2: spot-check, then hide moderate-download skills matching the same pattern.
• Phase 3: upgrade within a short deadline or hide only after the upgrade decision is reviewed.
• Phase 4: merge or hide repeated families only after target review.
• Do not delete by default.

Prefer hide before delete because clawhub hide is reversible with clawhub unhide <slug>.

Approval And Execution

Generated command files are intentionally commented out. Treat them as previews, not scripts to run blindly.

Safe command forms after explicit approval:

clawhub hide <slug> --yes
clawhub unhide <slug> --yes
clawhub inspect <slug> --files
clawhub publish <path>
clawhub skill rescan <slug>

Higher-risk command form:

clawhub skill merge <source-slug> <target-slug> --yes

Merge is higher risk because no obvious unmerge command is available. Review the canonical target before approving merge batches.

Responding To Users

For skills with comments or reported issues:

1. Inspect the skill with clawhub inspect <slug> --files.
2. Find or reconstruct the local source.
3. Reproduce or understand the issue.
4. Patch the source skill.
5. Publish the update with clawhub publish <path>.
6. Rescan if needed with clawhub skill rescan <slug>.
7. Reply with what changed, the new version, and any remaining limitation.

If comment bodies are unavailable through the API or CLI, say that only comment counts are visible and ask for a browser workflow or comment export.

Dashboard Maintenance

The dashboard is a local generated artifact:

python3 scripts/update_all.py --handle <clawhub-handle>

Open reports/index.html after refresh. It is safe to regenerate; it should not be packaged into the skill.

Each full refresh writes a timestamped snapshot under data/snapshots/<handle>/. When at least two snapshots exist, the dashboard shows the top 20 skills by new downloads and new installs since the previous snapshot. Use those growth charts to decide which skills are becoming popular and deserve priority maintenance.

Use --baseline when the account has materially changed and the next run should become the first active trend baseline. Existing active snapshots are archived under data/snapshots/<handle>/archive/ instead of deleted.

Safety Rules

• Never execute hide, merge, delete, or publish actions merely because a report recommends them.
• Never execute hide, merge, or delete actions when data_quality.status is partial.
• Never make maintenance, cleanup, or publish decisions from rows marked data_unavailable; retry collection later.
• Never batch-hide skills with installs, stars, comments, or strong usage without manual review.
• Do not treat zero downloads as evidence when detail fetches failed or profile totals disagree with processed totals.
• Use hide/private-style cleanup before deletion.
• Treat generated shell files as commented approval previews.
• Keep generated data, caches, logs, and reports out of the published skill package.
• If network or authentication fails, work from existing snapshots and clearly state the limitation.