CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

scan

Scans the codebase to generate project-doc.md and AGENTS.md. Use when bootstrapping a new agent-driven repo, refreshing project documentation after architectural changes, or running a delta scan to detect drift. Runs a full scan on first use and a smart delta scan on subsequent runs. Uses understand-anything + context-mode when available, falls back to native tools otherwise. Only updates AGENTS.md on detected architectural changes with human confirmation.

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Quality

Content

75%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, mostly executable multi-step workflow with genuine checkpoints (mode detection, early exit, human-confirmed AGENTS.md updates) and a properly linked one-level-deep reference. It falls short of top marks on four fronts in small doses: duplicated plugin-fallback instructions, an unspecified invocation for the core analysis tool, no validation loop on the written output, and the large output template inlined rather than split out.

Suggestions

State the plugins' optional status once and consolidate the fallback instructions into a single place (Step 1 or Step 3A) to remove the duplicated guidance and tighten conciseness.

Make the core analysis step executable: give the actual understand-anything invocation (or a concrete fallback recipe, e.g. a specific find/grep sequence per directory) instead of "use find, grep, cat, and git commands directly".

Add a validation feedback loop after writing/patching project-doc.md — e.g. re-read the patched sections and confirm they are internally consistent before reporting completion — to strengthen workflow clarity.

DimensionReasoningScore

Conciseness

The body is largely lean and template-driven with no concept explanations Claude already knows, but there is redundant padding: the plugins' optional status is stated twice ("These plugins are **optional**. They improve scan quality but are not required" after the check table already implies it) and the fallback approach is described in both Step 1 ("use find, grep, cat, and git commands directly...") and again in Step 3A. Not 5 because of this duplication; not 3 because the over-explanation is minor and localized.

4 / 5

Actionability

Concrete commands and paths throughout: `/plugin list | grep understand-anything`, `git diff HEAD~1 --name-only`, exact output paths (`.claude/pipeline/project-doc.md`), a complete project-doc.md template, and a literal confirmation prompt. The gap is the core analysis step: "Use `understand-anything` to analyse the entire codebase" gives no invocation, and the native fallback names tools without a command recipe. Not 5 because the central scanning action is not executable as written; not 3 because everything around it is concrete.

4 / 5

Workflow Clarity

Clear conditional sequencing: file-existence check picks FULL vs DELTA mode, delta scan has an early-exit checkpoint ("If no changed files, report... and exit"), and AGENTS.md updates require explicit human confirmation ([y]/[n]). Not 5 because there is no validation or feedback loop on the generated output — project-doc.md is written/patched with no step verifying the patched sections are accurate or coherent, and no error recovery if the analysis step fails. Not 3 because mode-detection, early-exit, and human-confirmation checkpoints are present; the writes are also not destructive to source code, so the destructive-operation cap does not apply.

4 / 5

Progressive Disclosure

The single bundle file (references/agents-template.md) is real, clearly signaled, and one level deep — "read and follow the complete [project-specific instruction template](references/agents-template.md), including its security rules and human-confirmed update requirements" — and the body is well-sectioned by step. Not 5 because the ~50-line project-doc.md output template is inlined in the body when it is exactly the kind of bulk structured content that could live in a second reference file; not 3 because organization is otherwise good and the existing reference is well-signaled.

4 / 5

Total

16

/

20

Passed

Description

83%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description that answers both what and when with an explicit, multi-scenario trigger clause and consistent third-person voice. Its main weaknesses are trigger-synonym coverage and the closing sentences spending description budget on implementation details (plugin names, fallback behavior) rather than user-facing capabilities.

Suggestions

Replace the implementation-detail sentences ("Uses understand-anything + context-mode when available, falls back to native tools otherwise") with a user-facing capability such as "documents the tech stack, architecture, folder structure, and code conventions", improving specificity without adding length.

Add natural trigger synonyms users would actually say — e.g. "document the codebase", "generate repo docs", "set up AGENTS.md" — to broaden trigger-term coverage beyond pipeline jargon like "delta scan" and "drift".

DimensionReasoningScore

Specificity

Lists several concrete actions — "Scans the codebase to generate project-doc.md and AGENTS.md", "Runs a full scan on first use and a smart delta scan on subsequent runs", "Only updates AGENTS.md on detected architectural changes with human confirmation" — but the final sentences describe implementation details (plugin usage, fallbacks) rather than capabilities, leaving minor coverage gaps. Not 5 because coverage is not comprehensive (e.g., what the generated documentation contains is never named); not 3 because it goes well beyond 1-2 actions.

4 / 5

Completeness

Clearly answers "what" ("Scans the codebase to generate project-doc.md and AGENTS.md") and "when" with an explicit Use-when clause listing three concrete trigger scenarios ("bootstrapping a new agent-driven repo, refreshing project documentation after architectural changes, or running a delta scan to detect drift"). Matches the anchor for explicit what AND when with concrete trigger phrases; not 4 because the when-clause is already explicit and specific.

5 / 5

Trigger Term Quality

Good natural keywords: "scans the codebase", "bootstrapping a new agent-driven repo", "refreshing project documentation", "delta scan to detect drift". A few natural terms users would say are missing ("document the codebase", "generate repo docs", "onboarding"), and "delta scan"/"drift" lean toward pipeline jargon. Not 5 because synonym coverage is incomplete; not 3 because several relevant natural phrases are present.

4 / 5

Distinctiveness Conflict Risk

Distinctive artifacts and jargon (project-doc.md, AGENTS.md, understand-anything, context-mode, delta scan) carve a clear niche, but "refreshing project documentation" overlaps with generic documentation-generator skills. Mostly distinct with minor overlap risk against closely related skills; not 5 because the documentation-refresh trigger is broad enough to collide with other doc skills.

4 / 5

Total

17

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

wshobson/agents

Path

plugins/ship-mate/skills/scan/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.