OpenParable
Skip to content
← Back to skills

Agent Ops Housekeeping

Productivity
agent-ops-housekeeping

Agent Ops Housekeeping is an Agent Skill for productivity published in the majiayu000/claude-skill-registry repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Comprehensive project hygiene: archive issues, validate schema, clean clutter, align docs, check git, update ignores.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/majiayu000/claude-skill-registry/blob/HEAD/skills/workflow/agent-ops-housekeeping/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/agent-ops-housekeeping, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Housekeeping

Keep the project clean, organized, and maintainable.

Reference: See REFERENCE.md for detailed procedures, CLI commands, gitignore checklist.


Core Tasks (Always Run)

  1. Archive completed issues → history.md
  2. Regenerate index.md → compact issue summary
  3. Validate issue schema → fix malformed issues
  4. Clean clutter → remove temp files, fix ignores

Issue Archival ⚡ (Auto-Run)

Runs automatically by default. Use --dry-run to preview.

Procedure:

  1. Scan ALL issue files including splits (*.md, *-*.md)
  2. Find issues with status: done, cancelled, dropped, wont-fix
  3. Append to history.md under ## Archived [YYYY-MM-DD]
  4. Remove from source file
  5. If history.md > 500 lines, rotate to archives/history-YYYYMMDD.md
  6. Check if split files can be compacted

Hygiene Checks

1. Issue File Management

  • Split files > 100K into numbered files
  • Compact split files when combined < 80K
  • Keep OLDEST in numbered files, NEWEST in main

2. Backlog Triage

Prompt to prioritize items with status: needs_triage or > 2 weeks old.

3. Schema Validation

Validate against .github/reference/issue-schema.json:

  • Required: id, type, priority, title, status
  • ID format: {TYPE}-{NNNN}@{HHHHHH}
  • Auto-fix: missing status, wrong priority file

4. Clutter Detection

Find generated/stale markdown outside .agent/docs/.

5. README Alignment

Check if README reflects actual project state.

6. Git Health

  • Uncommitted changes count
  • Untracked files
  • Stale branches (30+ days)
  • Large uncommitted files

7. Gitignore Audit

Check for missing ignores: node_modules, .venv, dist, build, .env

8. State File Health

  • Required files exist
  • Valid YAML frontmatter
  • No orphaned references

Invocation

/agent-housekeeping           # Full sweep (archives automatically)
/agent-housekeeping --dry-run # Preview only
/agent-housekeeping --fix     # Auto-fix safe issues
/agent-housekeeping issues    # Just archival
/agent-housekeeping git       # Just git health

When to Run

  • After completing milestone/feature
  • Before starting new major work
  • Weekly maintenance
  • When context feels cluttered
  • Before handoff