skills.rest
MaiconGambini
MaiconGambiniCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

harness-readable-workspace

Audit repository files to verify a fresh agent session can orient without chat history.

Updated Jul 29, 2026
Search Tags:#documentation#onboarding#audit#repository#session continuity#opencode#agent harness
One-click install
npx skills add https://github.com/MaiconGambini/opencode-harness-guide --skill harness-readable-workspace-maicongambini
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: harness-readable-workspace
Source: https://github.com/MaiconGambini/opencode-harness-guide/tree/main/skills/harness-readable-workspace
Command: npx skills add https://github.com/MaiconGambini/opencode-harness-guide --skill harness-readable-workspace-maicongambini

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When an agent harness is modified, new sessions may fail to orient because key context lives only in chat history instead of repository files. This Skill detects those documentation gaps before they break session continuity. ## Core Features & Use Cases - Fresh-Session Simulation: Answers six orientation questions (purpose, organization, install, verification, progress, next task) using only repo files. - Gap Diagnosis Table: Maps each unanswerable question to a root cause and a concrete fix, such as updating AGENTS.md, STATE.md, or feature_list.json. - Structured Audit Output: Reports each question with answerable status, source file, and proposed fix, requiring user approval before writing changes. - Use Case: After refactoring your OpenCode harness configuration, run this audit to confirm a brand-new session can still determine what the system does and what task comes next. ## Quick Start Audit this repository to check whether a fresh agent session can orient itself from the repo files alone.

Frequently Asked Questions about harness-readable-workspace

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I test if a new agent session can understand my repository?▼

Simulate a fresh session by reading only repository files and answering six questions: what the system does, how it is organized, how to install and start it, how to verify it works, current progress, and the next task. Any unanswerable question indicates a documentation gap.

What files does an agent need to orient in a new session?▼

The audit checks AGENTS.md for a system summary and quick start commands, STATE.md for current progress and a decisions log, and feature_list.json for an in_progress feature marking the next task.

Why does a new session fail to orient after harness changes?▼

Orientation fails when key context exists only in prior chat history rather than in files. Common causes are a missing AGENTS.md summary, a stale STATE.md, or no feature marked in_progress in feature_list.json.

Does this audit modify my repository files automatically?▼

No. The audit reports each question with its answerable status, source file, and identified gap, then proposes one fix per gap. It asks for user approval before writing any changes.

When should I run a fresh-session readability audit?▼

Run it whenever the harness has been modified or when a new session fails to orient correctly. It is a diagnostic check, not a continuous monitor, so it fits post-change verification workflows.

Related Skills

Explore More Software Engineering Skills→
firstsun-devfirstsun-dev
3

firstsun-harness

Scaffold, validate, and benchmark coding-agent harness files for repositories.

Official
Advanced
erikhazzarderikhazzard
1

eval__implement-proof-gate

Generate and validate test artifacts for approved objective gates.

Community
Advanced
FlexNetOSFlexNetOS

kb-close

Validate acceptance criteria and completion evidence before closing tasks.

Official
Intermediate
markeriksonmarkerikson
41

replay-playwright

Configure Replay Playwright plugin to record test executions for debugging.

Community
Intermediate