CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs-sync

Find and fix the docs and agent guidance that a branch makes stale - agent skills and their reference files, AGENTS.md and .agents/*.md prompts, READMEs, docs/ folders, and code-adjacent docs that name a changed path, command, symbol, env var, setting, endpoint or behaviour. Use before opening a PR, before pushing new commits to an open PR, and when asked to update docs or skills after a change. The open-pr skill runs it every time.

79

Quality

99%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

100%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 lean, highly actionable procedure: concrete executable commands at every step, a clear six-phase sequence with an explicit final verification check and done-when checklist guarding a batch-edit workflow, and well-organized single-file structure with no content that should be split out. It assumes Claude's competence throughout and adds only repo-specific knowledge Claude could not infer on its own.

DimensionReasoningScore

Conciseness

The body is dense, instruction-only prose: every sentence directs an action ("Run every command from the repo root. Shell variables do not carry over between commands: run each code block as one command.") and nothing explains concepts Claude already knows. The two-sentence intro earns its place by stating when and why to run the skill; there is no padding to trim, matching the anchor-5 'every token earns its place' case rather than anchor 4's 'minor instances of over-explanation'.

5 / 5

Actionability

The guidance is fully executable: step 1 gives copy-paste-ready git/gh pipelines (the grep -E over diff lines, the sed extraction of '@@' hunk headers), step 2 gives a complete git grep invocation with a worked TERMS example, and step 6 gives the final verification grep. Placeholders (<the base from open-pr Step 2, else main>, <doc files>) are clearly labeled inputs the agent fills from prior output, which the rubric treats as justified flexibility rather than pseudocode; the common cases are covered concretely.

5 / 5

Workflow Clarity

Six clearly sequenced steps (find changes → find stale docs → update in place → prohibited edits → commit/report → done-when) with an explicit validation checkpoint: the final grep in section 6 "prints only the hits that you noted as still true", and the 'Done when' checklist requires every hit to be updated or explicitly justified. Because this batch-edit workflow does include verification steps, the destructive/batch cap at 3 does not apply, and the sequence matches the anchor-5 pattern of explicit validation plus a completion checklist.

5 / 5

Progressive Disclosure

The skill is a single self-contained procedure (~90 lines, no references/, scripts/, or assets/ directories exist) organized into six numbered sections that mirror the workflow, so navigation is trivial. Nothing belongs in a separate file — the grep/diff pipelines are the core procedure, not reference material — so content placement is appropriate and there are no buried or nested references; this fits anchor 5's 'content appropriately split / easy navigation' better than anchor 4, which would require identifying a real organization gap.

5 / 5

Total

20

/

20

Passed

Description

100%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.

An exemplary description: concrete find-and-fix actions, a comprehensive enumeration of target files and change types, an explicit and specific 'Use when' clause with natural trigger phrases, and a well-defined niche that avoids conflicts with adjacent skills. Voice is appropriately imperative/third-person with no first- or second-person phrasing.

DimensionReasoningScore

Specificity

The description opens with concrete actions ("Find and fix the docs and agent guidance that a branch makes stale") and comprehensively enumerates both the target artifacts ("agent skills and their reference files, AGENTS.md and .agents/*.md prompts, READMEs, docs/ folders, and code-adjacent docs") and the change types they go stale on ("path, command, symbol, env var, setting, endpoint or behaviour"). Coverage is comprehensive with no vague filler, matching the anchor-5 example's breadth; anchor 4 would require identifiable gaps in coverage, and none are present.

5 / 5

Completeness

It explicitly answers both questions: what ("Find and fix the docs and agent guidance that a branch makes stale", with the full target enumeration) and when ("Use before opening a PR, before pushing new commits to an open PR, and when asked to update docs or skills after a change"). This matches the anchor-5 example's structure of concrete capability list followed by explicit trigger phrases; anchor 4 would require a less specific when-clause, which is not the case here.

5 / 5

Trigger Term Quality

It contains the natural phrases a user would actually say when needing this skill: "update docs or skills", "stale", "READMEs", "before opening a PR", "pushing new commits", plus variations like "skills", "prompts", "docs/ folders", and "env var". This meets the anchor-5 bar of comprehensive natural-term coverage including synonyms; the anchor-4 case ("a few natural terms missing") would require missing common phrasings, and the key user utterances are all covered.

5 / 5

Distinctiveness Conflict Risk

It carves a clear niche — docs/agent-guidance staleness created by a branch's changes — with triggers tied to the PR lifecycle ("before opening a PR, before pushing new commits to an open PR") rather than generic documentation work, minimizing overlap with general doc-editing or commit-message skills. The anchor-5 fit is direct; anchor 4 would imply overlap with a closely related skill's triggers, and none applies.

5 / 5

Total

20

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 1 missing

Warning

Total

15

/

16

Passed

Repository

Kiln-AI/Kiln

Path

.agents/skills/docs-sync/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.