---
name: content-freshness-loop
description: Use when deploying the loopmaster.ai content-freshness template to audit stale docs, broken links, and source-backed content updates.
category: loops
requirements:
  - Python 3
  - repository checkout containing templates/content-freshness
  - uv for manifest validation, or preinstalled pyyaml/jsonschema for tools/validate_manifests.py
  - cron, GitHub Actions, or Hermes kanban depending on backend choice
  - no paid API credential for the default dry run
public: true
deploys-template: content-freshness
backends:
  - cron
  - github_actions
  - agent_kanban
---

# Content freshness loop skill

Use this pack to install or verify `content-freshness` without copying the template guide. The template remains the source of truth; this skill is the thin operator checklist.

Canonical references:

- `templates/content-freshness/loop.yaml` — permissions, gates, state paths, verification commands, and backend hints.
- `templates/content-freshness/AGENT-INSTALL.md` — complete backend install guide.
- `templates/content-freshness/scripts/content_freshness.py` — checked-in runner used by every backend.
- `templates/content-freshness/examples/dry-run-targets.json` — local-only target config for scratch verification.
- `templates/content-freshness/examples/targets.json` — editable target config for real installs.

If this pack conflicts with `templates/content-freshness/AGENT-INSTALL.md`, follow the template guide and fix this pack.

## Preflight from repo root

```bash
test -f templates/content-freshness/loop.yaml
test -f templates/content-freshness/AGENT-INSTALL.md
python3 templates/content-freshness/scripts/content_freshness.py --help >/tmp/loopmaster-content-freshness-help.txt
uv run --with check-jsonschema --with pyyaml check-jsonschema --schemafile spec/loop.schema.json templates/content-freshness/loop.yaml
```

Expected result: each command exits 0 and manifest validation prints `ok -- validation done`.

## Pick a backend

- cron: shortest local path; writes reports/state in the checkout from a persistent env file.
- GitHub Actions: repository scheduler; writes report/state artifacts and opens a PR for review.
- agent-kanban: recurring agent task; the task must run the Python helper before making follow-up cards.

Use `templates/content-freshness/AGENT-INSTALL.md` for the exact backend steps.

## Fast scratch verification

This is not a live install. It proves the runner and duplicate-safe report path under `/tmp`.

```bash
rm -rf /tmp/loopmaster-content-freshness /tmp/loopmaster-content-freshness-state.json
python3 templates/content-freshness/scripts/content_freshness.py \
  --targets templates/content-freshness/examples/dry-run-targets.json \
  --state /tmp/loopmaster-content-freshness-state.json \
  --output-dir /tmp/loopmaster-content-freshness \
  --max-link-checks 5
```

Expected stdout shape: `CONTENT_FRESHNESS_REPORT=...`, `CONTENT_FRESHNESS_STATE=...`, `FINDINGS=...`, `AUDIT_ERRORS=0`, and `LINKS_CHECKED=...`.

## Install notes

For a real install, copy or adapt `templates/content-freshness/examples/targets.json`, then follow the backend section in `templates/content-freshness/AGENT-INSTALL.md`. Keep env files out of git and never rely on one-time shell exports for cron.

## Stop or roll back

- cron: remove the crontab line that runs `templates/content-freshness/scripts/content_freshness.py`.
- GitHub Actions: disable or delete the copied workflow in a PR.
- agent-kanban: pause or remove the recurring task.
- Bad report: close/revert the report PR or delete local artifacts after recording the failure.

## First-week ownership checklist

- Confirm every finding cites a file path, URL, or source check.
- Confirm broken/skipped links are separated from stale-content findings.
- Tune noisy targets before expanding scope.
- Keep public publishing and content rewrites human-gated.