CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

keep-docs-in-sync

Keep documentation in sync with a code or contract change in the SAME PR. Use whenever you change an interface, wire field, endpoint, config field, default, harness/backend value, or runtime behavior, and after any implement-feature slice that lands such a change. Triggers - "keep docs in sync", "update the docs too", "the docs drifted", "document this change", "did we update the inventory". Maps a change to every doc that describes it (design docs, the agent-workflows documentation/ pages, the interface inventory + its index, AGENTS.md, skills) and enforces one source of truth.

Quality

95%

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

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

This is a high-quality instruction-only skill body: lean, dense with executable grep commands and exact paths, and a clearly sequenced procedure with an explicit re-grep-to-zero verification step and a completion checklist. The only structural improvement would be moving the repo-specific documentation-surface map into a one-level reference file.

Suggestions

Move the agent-workflows doc-surface listing in step 2 (documentation/ pages, interfaces inventory, AGENTS.md, project workspace) into a clearly signaled reference file (e.g. doc-surface.md) so the core procedure stays scannable while repo-specific detail is progressively disclosed.

The 'When this applies' bullet list partially duplicates the frontmatter description's trigger conditions; consider trimming it to the delta (e.g. the file/symbol-citation case) to save tokens.

DimensionReasoningScore

Conciseness

The body is lean and operational with no explanation of concepts Claude already knows — e.g. "If you removed a thing, delete its page and its index row, not just its prose" and "Two copies drift; a pointer does not" compress policy into single terse lines. The brief opening rationale earns its place by justifying the deletion and cross-link rules, so it fits 'every token earns its place' rather than the 4 anchor's 'minor instances of over-explanation'.

5 / 5

Actionability

Guidance is copy-paste ready: executable commands like `grep -rn "<old name or field>" docs/ --include=*.md` and `rg -l ... --glob '**/AGENTS.md'`, exact paths ("docs/design/agent-workflows/interfaces/"), and concrete field-level specifics ("the row and its Status column: stable / evolving / declared-not-wired"). For an instruction-only skill this fully matches the 'specific examples cover the common cases' anchor; the placeholder in the grep commands is appropriate templating, not pseudocode.

5 / 5

Workflow Clarity

A five-step procedure is clearly sequenced with an explicit validation/feedback loop — step 5: "Re-grep for the old name to confirm zero stragglers. Check that any file or line citation you touched still resolves" — reinforced by a pre-done checklist. This matches the top anchor (explicit validation, error-recovery re-check, checklist) for what is a batch edit operation, and is clearly above the 4 anchor's 'minor validation gaps'.

5 / 5

Progressive Disclosure

The single file is well organized into clear sections (When this applies / The procedure / external-integration caveat / checklist) with no nested or buried references, matching 'good structure; most content is appropriately placed'. It stops short of 5 because the body runs well past 50 lines and the repo-specific doc-surface map in step 2 (documentation/ pages, inventory, AGENTS.md, project workspace) is bulky enough that it could live in a clearly signaled one-level reference file, keeping the procedure itself tighter.

4 / 5

Total

19

/

20

Passed

Description

95%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: it states what the skill does and exactly when to use it, lists natural trigger phrases users would actually say, and scopes itself to a distinct same-PR doc-sync niche. The only soft spot is that its action verbs ('maps', 'enforces') are slightly abstract compared to the concrete doc categories it names.

DimensionReasoningScore

Specificity

Quotes like "Maps a change to every doc that describes it (design docs, the agent-workflows documentation/ pages, the interface inventory + its index, AGENTS.md, skills) and enforces one source of truth" name concrete doc categories and specific change targets ("wire field, endpoint, config field, default, harness/backend value"), matching the 'several specific actions; minor gaps' anchor. It falls short of 5 only because the core verbs 'maps' and 'enforces' stay one level abstract rather than enumerating the individual actions (grep, edit, delete, cross-link) the skill performs.

4 / 5

Completeness

It explicitly answers both: what — "Keep documentation in sync with a code or contract change in the SAME PR" plus the mapping/one-source-of-truth behavior; and when — "Use whenever you change an interface, wire field, endpoint, config field, default, harness/backend value, or runtime behavior, and after any implement-feature slice". This matches the top anchor with concrete trigger phrases, clearly above the 4 anchor where 'when' could be more specific.

5 / 5

Trigger Term Quality

The explicit trigger list — "keep docs in sync", "update the docs too", "the docs drifted", "document this change", "did we update the inventory" — covers natural synonyms and phrasings a user would genuinely say, matching the comprehensive-coverage anchor. It is not 4 because no obviously common natural variation is missing; the phrases span command, reminder, and question forms.

5 / 5

Distinctiveness Conflict Risk

The niche is distinct — same-PR doc synchronization with repo-specific anchors like "the interface inventory + its index" and trigger "did we update the inventory" — so it is unlikely to fire for a generic writing or code skill. It clearly fits the 'clear niche with distinct triggers; minimal conflict risk' anchor rather than the 4 anchor's 'minor overlap risk with closely related skills'.

5 / 5

Total

19

/

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

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

Total

15

/

16

Passed

Repository

Agenta-AI/agenta

Path

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