CtrlK
BlogDocsLog inGet started
Tessl Logo

updating-noridocs

Use this when you have finished making code changes and you are ready to update the documentation based on those changes.

52

Quality

66%

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

Fix and improve this skill with Tessl

tessl review fix ./.agency/plugins/nori/skills/updating-noridocs/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

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

The content delivers a clear three-step workflow with checklists, an explicit validation step, and a complete format template — actionable and well-structured throughout. Its main weaknesses are redundancy between the Common Mistakes and Red Flags sections and a dispatch step shown as pseudo-syntax rather than a ready-to-use example, plus a missing retry loop when verification finds inaccurate updates.

Suggestions

Merge "Common Mistakes" and "Red Flags" into a single section — they repeat the same three points (provide context, verify, focus on architecture) and cost tokens twice.

Replace the `Task(subagent_type: nori-change-documenter)` pseudo-call with a concrete example of the subagent invocation including a short filled-in prompt, making the dispatch step copy-paste ready.

Add an explicit feedback loop after verification: what to do when `git status`/diff review shows missing or inaccurate docs.md updates (e.g. re-dispatch the subagent with the specific correction).

DimensionReasoningScore

Conciseness

The body is mostly efficient — the process steps, format template, and checklists all earn their place — but the "Common Mistakes" and "Red Flags" sections substantially repeat each other ("Skip providing context" vs "Provide detailed context"; "Skipping verification" vs "Assume docs were updated without verifying"), and the core principle line plus announce-at-start line add ceremony. This matches 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than 4, where the over-explanation would be only minor.

3 / 5

Actionability

Mostly executable guidance: concrete checklists for context gathering, an explicit list of what to include in the subagent prompt, the verification command `git status`, and a complete docs.md format template. It falls short of 5 because the dispatch step is shown as non-executable pseudo-syntax (`Task(subagent_type: nori-change-documenter)` in a bash block) with no example prompt text to adapt, leaving a minor gap the user must fill.

4 / 5

Workflow Clarity

The three-step sequence (Gather Context → Dispatch subagent → Verify) is clearly ordered with checklists and a dedicated validation step (run `git status`, review diffs, check that updates focus on architecture). Not 5 because the verification step lacks an explicit feedback loop — there is no 'if the diffs are wrong or docs were missed, re-dispatch with corrective context' instruction, so error recovery is implicit.

4 / 5

Progressive Disclosure

No bundle files exist, and the body is well-organized into distinct sections (Process, Format, Common Mistakes, Red Flags) with the heavier material — the full docs.md template — in one clearly signaled block. It is not 5 because at ~113 lines the Noridocs Format template is a natural candidate for a one-level-deep reference file, keeping SKILL.md as a lean overview; it is well above 3 since nothing is buried and all content is appropriately placed for a single-file skill.

4 / 5

Total

15

/

20

Passed

Description

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

The description has a clear, explicit 'Use when' trigger tied to finishing code changes, but the 'what' is generic — it never names noridocs/docs.md files or mentions the subagent-based mechanism, and it is written in second person, which costs it specificity. Keywords cover the basic scenario but miss the natural synonyms ('docs', 'docs.md', 'noridocs') that would distinguish this skill from generic documentation helpers.

Suggestions

State the concrete what and scope, e.g. 'Updates noridocs (per-folder docs.md files) to reflect code changes by dispatching the nori-change-documenter subagent' — this both fixes the vague 'what' and restores the specificity point lost to second-person phrasing.

Rewrite in third person to comply with the voice convention: 'Updates folder-level docs.md files...' instead of 'Use this when you have finished...'.

Add distinguishing trigger keywords such as 'docs.md', 'noridocs', and 'update the docs after my changes' to reduce overlap with generic documentation skills.

DimensionReasoningScore

Specificity

The only action named is the generic "update the documentation based on those changes" — it never says what documentation (docs.md files, noridocs) or how (dispatching a subagent), matching the anchor 'Names the domain but actions are minimal or generic' (2). It is additionally penalized one point per the judging guidelines for second-person voice ("Use this when you have finished making code changes and you are ready..."), dropping it to 1.

1 / 5

Completeness

The 'when' is explicit and well-triggered ("Use this when you have finished making code changes and you are ready to update the documentation"), and a 'what' is present ("update the documentation"), so both halves exist — matching anchor 4. It is not 5 because the 'what' is vague: it never identifies which documentation (noridocs/docs.md files) or what the skill concretely does, and it is not 3 because the 'when' clause is fully explicit rather than weakly implied.

4 / 5

Trigger Term Quality

"code changes" and "update the documentation" are natural phrases a user might say, but common variations and synonyms are missing — no "docs", "docs.md", "noridocs", or "after my change". This matches 'Some relevant keywords but missing common variations or synonyms', not 4 (which would require broader keyword coverage) and not 2 (keywords here are domain-relevant, not generic filler like 'works with files').

3 / 5

Distinctiveness Conflict Risk

The post-code-change trigger condition is reasonably distinct, but the operative term "documentation" is broad and would overlap with any doc-generation or README-updating skill; the skill's actual niche (noridocs/docs.md maintenance via a subagent) is absent from the description. This sits at 'somewhat specific but could still overlap with similar skills' — not 4, since the missing niche term leaves real overlap risk with generic documentation skills.

3 / 5

Total

11

/

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
microsoft/FluidFramework
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.