assess
Step back and critically reassess project state. Use when asked to "assess", "step back", "fresh eyes", "check alignment", "sanity check", "health check", "prune documentation", or "evaluate what's working". Offers documentation pruning and doc-code alignment analysis. Offer to run after major changes (don't auto-run).
npx skills add majiayu000/claude-skill-registry --skill assess-grahama1970-agent-skills-2 --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
The skill guides a back-to-basics reassessment of the project, emphasizing documentation pruning and alignment analysis. It supports both interactive guidance and automated output via a run script that produces structured JSON reports. It categorizes findings into doc-code alignment and documentation quality, and offers a collaborative, question-driven process to determine priorities.
How it works
- Interactive usage guides the user through a collaborative assessment flow, asking clarifying questions about scope, focus areas (code quality, doc accuracy, or both), and known issues.
- Step 2 detects the project ecosystem by looking for standard metadata marker files (e.g., pyproject.toml, package.json, Cargo.toml, go.mod, Gemfile, composer.json) to identify Python, Node.js, Rust, Go, Java, Ruby, PHP environments, then reads ecosystem-specific metadata as applicable.
- Universal project docs (README.md, CONTEXT.md, AGENTS.md, docs/, etc.) are scanned to establish a baseline inventory.
- Step 3 performs a quick scan: read project metadata, read README, glob structure, and produce 2-3 initial observations.
- Step 4 enables a deep dive based on user guidance, evaluating findings for blocking issues, debt, and required fixes.
- Step 5 presents collaborative recommendations and questions to decide which items to fix or update.
- Assessment is organized into categories, notably Doc-Code Alignment and Aspirational vs Implemented, with guidance on potential actions and questions to ask the user.
When to use it
Use when the user asks to reassess project state, perform a documentation cleanup, prune documentation, or validate doc-code alignment. Trigger phrases include: "assess", "step back", "prune documentation", "documentation audit", and related variations listed in the triggers. The skill supports running an automated JSON report via a provided script (assess.py) when in programmatic mode.
What it can touch
- Programmatic workflow uses:
assess.pyto generateassessment.json. - Ecosystem discovery relies on standard files (e.g.,
pyproject.toml,package.json,Cargo.toml,go.mod,Gemfile,composer.json). - Documentation inventory and cross-reference checks target common docs like
README.md,CONTEXT.md,AGENTS.md, anddocs/.
Caveats
- The tool emphasizes collaboration and user-driven depth; it does not auto-run changes without explicit user instruction.
- Outputs rely on the presence of standard metadata; absence may lead to fallback discovery behaviors.
- Actionability depends on user guidance and prioritization of findings; the skill does not enforce fixes by itself.
# Assess Skill Step back and critically reassess the project state. This skill provides both **interactive guidance** (human-in-the-loop) and **programmatic analysis** (automated pipelines). **Specialized for documentation pruning and doc-code alignment analysis.** ## CLI Usage (Programmatic) For automated pipelines (like Nightly Dogpile), use the `assess.py` script to generate structured JSON reports. ```bash # Run assessment and output JSON .pi/skills/assess/assess.py run . --output assessment.json # Categories: # - aspirational: TODOs, stubs # - brittle: FIXMEs, hardcoded secrets # - over_engineered: (Future) textual analysis # - working_well: (Future) test coverage stats ``` ## Interactive Usage (Human-in-the-Loop) Step back and critically reassess the project state. This skill guides the agent through systematic, **collaborative** evaluation. ## Key Principle: Collaborative Assessment Assessment is a dialogue, not a report. Ask clarifying questions to: - Understand what the user considers most important - Clarify intent when documentation is ambiguous - Prioritize findings based on user's goals - Confirm assumptions before making recommendations ## Assessment Flow ### Step 1:
- CLI Usage (Programmatic)
- Interactive Usage (Human-in-the-Loop)
- Key Principle: Collaborative Assessment
- Assessment Flow
- Step 1: Scope the Assessment
- Step 2: Find Project Root & Detect Ecosystem
- Step 3: Quick Scan & Initial Findings
- Step 4: Deep Dive
- Step 5: Collaborative Report
- Assessment Categories
- 1. Doc-Code Alignment (Documentation Pruning)
- 2. Aspirational vs Implemented
- 3. Brittle Code
- 4. Non-Working Code
Run assessment and output JSON Search for TODOs rg "TODO|FIXME|HACK|XXX" --type py Find Python files modified recently fd -e py --changed-within 7d Search for stub implementations rg "raise NotImplementedError|pass$" --type py
What does the assess skill do?
Step back and critically reassess project state. Use when asked to "assess", "step back", "fresh eyes", "check alignment", "sanity check", "health check", "prune documentation", or "evaluate what's working". Offers documentation pruning and doc-code alignment analysis. Offer to run after major changes (don't auto-run).
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill assess-grahama1970-agent-skills-2 --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.