CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

docs-sync

Use this skill whenever a pull request is opened, reopened, or synchronized in microsoft/apm to assess whether and how the documentation corpus must change to stay truthful with the proposed code change. Activate even when the PR title or body says nothing about docs -- the skill must run on every PR to detect silent drift between code and docs. Classifies impact as no-change, in-place edit (one to a few paragraphs), or structural change (new page or TOC reshape), then orchestrates a CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop to produce a patch-ready advisory. Does NOT review code quality, security, or test coverage. Does NOT auto-merge or auto-push doc edits.

Quality

85%

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

73%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-architected orchestration skill: explicit invariants, a validated multi-step pipeline with feedback loops, and correct use of separate schema/template asset files. Its main weakness is repeated governance hedging in Step 7 and non-operational jargon that inflate the token budget without adding executable value.

Suggestions

Consolidate Step 7's consent/ratification disclaimers (repeated across Step 7, the anti-patterns, and the invariants) into a single authoritative statement — or move the governance detail into a reference file — to lift conciseness.

Remove or explain non-operational tokens: the internal pattern codes ('A1 PANEL + B1 FAN-OUT/SYNTHESIZER + A8 ALIGNMENT LOOP') and the PR-specific reference ('PR 1244 class') do not guide execution.

Specify the fan-out mechanics concretely (how the '~10 KB bounded context' is assembled and the exact 'safe-outputs.add-comment' invocation) to close the remaining actionability gaps.

DimensionReasoningScore

Conciseness

Mostly efficient operational content (invariants, roster, cost table, checklist), but Step 7 and the Anti-patterns restate the same consent/ratification disclaimer three times ('never ratifies scope', 'neither bot advice, a review, historical acceptance, silence, nor a label is consent', 'Only the fresh responsible-human issue-scope checkpoint permits implementation'), and non-operational tokens like 'A1 PANEL + B1 FAN-OUT/SYNTHESIZER + A8 ALIGNMENT LOOP' and 'PR 1244 class' pad the text. Not 4 because the repetition is more than minor; not 2 because most sections earn their place.

3 / 5

Actionability

Concrete, copy-paste-ready commands ('gh pr comment --edit-last', 'node scripts/governance/eligibility.cjs --repo microsoft/apm --issue N --approval-url URL', 'apm <verb> --help'), exact comment headers, branch naming, a cost table, and validation against real asset schemas. Not 5 because some execution mechanics are only named, not specified (the '~10 KB bounded context' construction and the 'safe-outputs.add-comment' interface).

4 / 5

Workflow Clarity

Steps 1–7 are clearly sequenced with explicit validation at every handoff: schema-validate the classifier return with abort-on-failure, schema-validate every panelist return, a refuted-claims feedback loop that re-runs the writer, a bounded CDO alignment loop (N <= 3 redrafts with a defined exit), and defined cost-ceiling truncation behavior. This meets the batch-operation validation bar.

5 / 5

Progressive Disclosure

The body is an overview with one-level-deep, clearly signaled references to real bundle files (assets/classifier-return-schema.json, assets/panelist-return-schema.json, assets/advisory-comment-template.md — all present) plus a roster table linking each sub-skill and agent. Not 5 because the long Step 7 governance prose is inlined in SKILL.md rather than split into a reference file like the schemas and template.

4 / 5

Total

16

/

20

Passed

Description

92%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: concrete capabilities, explicit trigger conditions with event-level specificity, and explicit boundary carve-outs. The only gap is a handful of natural user phrasings for documentation drift.

DimensionReasoningScore

Specificity

Lists multiple specific concrete actions with comprehensive coverage: 'Classifies impact as no-change, in-place edit (one to a few paragraphs), or structural change (new page or TOC reshape), then orchestrates a CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop to produce a patch-ready advisory.' Named impact categories, a named persona panel, and a concrete deliverable leave no significant capability gaps.

5 / 5

Completeness

Explicitly answers both questions: the 'what' (classify impact into three named outcomes, orchestrate a persona panel, produce a patch-ready advisory) and the 'when' ('Use this skill whenever a pull request is opened, reopened, or synchronized in microsoft/apm', reinforced by 'Activate even when the PR title or body says nothing about docs').

5 / 5

Trigger Term Quality

Good natural keyword coverage: 'pull request is opened, reopened, or synchronized', 'PR title or body says nothing about docs', 'code change', 'drift'. It misses some natural user variations (e.g. 'documentation update', 'docs are stale/out of date'), so coverage is good rather than comprehensive.

4 / 5

Distinctiveness Conflict Risk

A clear niche (per-PR documentation-impact assessment in microsoft/apm) with explicit negative scope — 'Does NOT review code quality, security, or test coverage. Does NOT auto-merge or auto-push doc edits' — leaving minimal conflict risk with adjacent skills.

5 / 5

Total

19

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 9 suspicious

Warning

referenced_paths_exist

Referenced path issues: 2 missing, 2 deeper-than-1-level

Warning

Total

14

/

16

Passed

Repository

microsoft/apm

Path

.apm/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.