Flywheel
Check whether agent sessions are actually promoting learnings into durable .agents knowledge pools.
Overview
Flywheel is an agent skill most often used in Operate (also Build agent-tooling) that audits knowledge-pool health so future sessions can find promoted learnings.
Install
npx skills add https://github.com/boshu2/agentops --skill flywheelWhat is this skill?
- Reports flywheel health with optional JSON via --json
- Measures learnings, patterns, research, and retros pool counts under .agents/
- Models loop: Sessions → Transcripts → Forge → Pool → Promote → Knowledge
- Surfaces velocity vs friction bottlenecks in the knowledge pipeline
- Background-tier internal skill tied to wiki-knowledge-surface and lean-startup practices
- Measures four pools: learnings, patterns, research, retros
- Six-step flywheel model from Sessions through Promote back to future sessions
Adoption & trust: 786 installs on skills.sh; 384 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You run many agent sessions but cannot tell if transcripts are forging into durable .agents learnings or stalling at empty pools.
Who is it for?
AgentOps adopters maintaining .agents/learnings, patterns, research, and retros between coding sessions.
Skip if: Builders without an AgentOps repo layout or who only need DORA metrics on human CI—not agent knowledge surfaces.
When should I use this skill?
User runs /flywheel or asks to check knowledge flywheel health in an AgentOps repo.
What do I get? / Deliverables
You get a flywheel health report (stdout or JSON) with pool counts and friction framing so you can promote or write more .agents/learnings/*.md.
- Flywheel health report on stdout
- Optional JSON health payload when --json is supported
- Pool count snapshot for learnings, patterns, research, retros
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Operate/iterate is where you measure whether prior agent work compounds; flywheel health is a production habit loop, not a one-off build task. Iterate subphase fits continuous improvement of agent knowledge velocity and friction after sessions ship artifacts.
Where it fits
End-of-week review: run /flywheel to see if learnings pool grew after five feature sessions.
After scaffolding .agents directories, baseline pool counts before enabling promotion workflows.
Treat satisfaction of knowledge discovery as a leading indicator before scaling more parallel agents.
How it compares
A repo-local health checker for agent knowledge compounding, not a generic observability MCP or wiki CMS.
Common Questions / FAQ
Who is flywheel for?
Operators and solo builders using AgentOps who want a quick bash-backed read on whether knowledge pools are growing after agent work.
When should I use flywheel?
During Operate iterate reviews after intense agent weeks; during Build agent-tooling when standing up .agents structure; skip if you do not use boshu2/agentops conventions.
Is flywheel safe to install?
It uses Read, Grep, Glob, and Bash on your repo—confirm scope in SKILL.md and check the Security Audits panel on this Prism page before enabling in CI.
SKILL.md
READMESKILL.md - Flywheel
# Flywheel Skill Monitor the knowledge flywheel health. ## The Flywheel Model ``` Sessions → Transcripts → Forge → Pool → Promote → Knowledge ↑ │ └───────────────────────────────────────────────┘ Future sessions find it ``` **Velocity** = rate of knowledge flowing through. **Friction** = bottlenecks slowing the flywheel. ## Execution Steps Given `/flywheel`: ### Step 1: Measure Knowledge Pools ```bash # Count top-level artifact files (avoid counting directories) LEARNINGS=$(find .agents/learnings -maxdepth 1 -type f 2>/dev/null | wc -l) PATTERNS=$(find .agents/patterns -maxdepth 1 -type f 2>/dev/null | wc -l) RESEARCH=$(find .agents/research -maxdepth 1 -type f 2>/dev/null | wc -l) RETROS=$(find .agents/retros -maxdepth 1 -type f 2>/dev/null | wc -l) echo "Learnings: $LEARNINGS" echo "Patterns: $PATTERNS" echo "Research: $RESEARCH" echo "Retros: $RETROS" ``` ### Step 2: Check Recent Activity ```bash # Recent learnings (last 7 days) find .agents/learnings -maxdepth 1 -type f -mtime -7 2>/dev/null | wc -l # Recent research find .agents/research -maxdepth 1 -type f -mtime -7 2>/dev/null | wc -l ``` ### Step 3: Detect Staleness ```bash # Old artifacts (> 30 days without modification) find .agents/ -name "*.md" -mtime +30 2>/dev/null | wc -l ``` ### Step 3.5: Check Cache Health ```bash if command -v ao &>/dev/null; then # Get citation report (cache metrics) CITE_REPORT=$(ao metrics cite-report --json --days 30 2>/dev/null) if [ -n "$CITE_REPORT" ]; then HIT_RATE=$(echo "$CITE_REPORT" | jq -r '.hit_rate // "unknown"') UNCITED=$(echo "$CITE_REPORT" | jq -r '(.uncited_learnings // []) | length') STALE_90D=$(echo "$CITE_REPORT" | jq -r '.staleness["90d"] // 0') echo "Cache hit rate: $HIT_RATE" echo "Uncited learnings: $UNCITED" echo "Stale (90d uncited): $STALE_90D" fi else # ao-free fallback: compute approximate metrics from files echo "Cache health (ao-free fallback):" echo "Active learnings (30d): $(find .agents/learnings/ -name '*.md' -mtime -30 2>/dev/null | wc -l | tr -d ' ')" echo "Forge candidates pending: $(ls .agents/forge/*.md 2>/dev/null | wc -l | tr -d ' ')" if [ -f .agents/ao/citations.jsonl ]; then echo "Total citations: $(wc -l < .agents/ao/citations.jsonl | tr -d ' ')" echo "Unique learnings cited: $(grep -o '"artifact_path":"[^"]*"' .agents/ao/citations.jsonl 2>/dev/null | sort -u | wc -l | tr -d ' ')" else echo "No citation data (citations.jsonl not found)" fi [ -f .agents/ao/outcomes.jsonl ] && echo "Session outcomes recorded: $(wc -l < .agents/ao/outcomes.jsonl | tr -d ' ')" fi ``` ### Step 4: Check ao CLI Status ```bash if command -v ao &>/dev/null; then ao metrics flywheel status 2>/dev/null || echo "ao metrics flywheel status unavailable" ao status 2>/dev/null || echo "ao status unavailable" ao maturity --scan 2>/dev/null || echo "ao maturity unavailable" ao anti-patterns 2>/dev/null || echo "ao anti-patterns unavailable" ao badge 2>/dev/null || echo "ao badge unavailable" # Knowledge maintenance ao dedup --merge 2>/dev/null || true ao contradict 2>/dev/null || true ao constraint review 2>/dev/null || true ao curate status 2>/dev/null || true ao metrics health 2>/dev/null || true ao metrics cite-report --days 30 2>/dev/null || true # Active pruning: archive stale, evict low-utility, and