updating-noridocs

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

Quality

68%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

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

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.

The content is a well-structured, actionable process skill with clear sequencing, concrete tool invocations, and a useful format template. Its main gaps are mild section redundancy, a pseudo-invocation for the Task tool, and the absence of an explicit verify-and-retry feedback loop.

Suggestions

Add an explicit feedback loop in Step 3 ('if diffs are inaccurate or missing, re-dispatch the subagent with refined context') to push workflow_clarity toward 5.

Collapse the overlapping 'Common Mistakes' and 'Red Flags' sections into one to remove redundancy and improve conciseness.

Replace the `Task(subagent_type: ...)` bash block with the actual tool-call format or a clearly labeled pseudocode note to remove the minor actionability gap.

Dimension	Reasoning	Score
Conciseness	The body is lean, assumes Claude's competence, and avoids explaining concepts Claude already knows; the only padding is mild redundancy between the 'Common Mistakes' and 'Red Flags' sections, fitting 'Efficient; minor instances of over-explanation that could be trimmed' rather than the fully lean anchor 5.	4 / 5
Actionability	It provides concrete guidance — a Task tool invocation, `git status`, checklists, and a full docs.md format template — but the Task call is shown in a bash block as a pseudo-invocation and a few specifics are left to the subagent, matching 'Mostly executable guidance; concrete code or commands with minor gaps' rather than copy-paste-ready anchor 5.	4 / 5
Workflow Clarity	The three-step process (Gather Context, Dispatch Subagent, Verify Updates) is clearly sequenced with checklist-driven checkpoints and an explicit verification step (git status, review diffs), but it lacks an explicit error-recovery feedback loop if verification fails, fitting anchor 4 rather than the full feedback-loop anchor 5.	4 / 5
Progressive Disclosure	The skill is self-contained with no bundle files and is well-organized into clearly signaled sections; the sizable Noridocs Format template is appropriate inline but the body exceeds the under-50-line simple-skill threshold, so it sits at 'Good structure; most content appropriately placed' rather than the well-split anchor 5.	4 / 5
	Total	16 / 20 Passed

Description

62%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 clearly answers both what and when with a concrete post-code-change trigger, but the 'what' is a single generic action and trigger-term coverage lacks synonyms. It is solid and actionable yet stops short of comprehensive.

Suggestions

List 2-3 specific documentation actions (e.g. 'regenerate folder docs.md files, refresh architecture notes, record new patterns') to lift specificity from 3 toward 5.

Add natural synonyms users might say such as 'docs', 'refactor', or 'after committing' to broaden trigger-term coverage.

Tighten the 'what' with a concrete noun (e.g. 'update Noridocs (docs.md files)') so the capability is explicit rather than implied.

Dimension	Reasoning	Score
Specificity	The description names the domain ('update the documentation') and one concrete action tied to code changes, but offers only that single generic action rather than a comprehensive set; this matches 'Names domain and 1-2 concrete actions, but not comprehensive' rather than the multi-action anchor 5 or the purely minimal anchor 2.	3 / 5
Completeness	It explicitly states both what ('update the documentation based on those changes') and when ('when you have finished making code changes and you are ready to update the documentation'), with a concrete trigger clause; the 'what' is somewhat generic so it stops short of the fully concrete anchor 5 but clearly exceeds the missing-when anchor 3.	4 / 5
Trigger Term Quality	It uses reasonably natural phrases ('finished making code changes', 'update the documentation') but provides no synonyms or variations (e.g. 'docs', 'refactor', 'commit'), fitting 'Some relevant keywords but missing common variations or synonyms' rather than the comprehensive anchor 5.	3 / 5
Distinctiveness Conflict Risk	The post-code-change trigger carves a fairly specific niche that is mostly distinct from general doc skills, with only minor overlap risk against closely related documentation skills, matching anchor 4 rather than the broad overlap of anchor 3 or the minimal-conflict anchor 5.	4 / 5
	Total	14 / 20 Passed

Validation

100%

Warnings & errors only

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
Path: .agency/plugins/nori/skills/updating-noridocs/SKILL.md
Commit: f02e424

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.