updating-architecture-docs

Use this skill when updating, reviewing, or creating architecture documentation in the architecture/ directory. This includes after refactors, feature additions, component changes, or when auditing docs for accuracy. Use it any time code changes affect how Cog's internals work -- new packages, changed IPC protocols, modified build pipeline, runtime behavior changes. Also use it proactively when reviewing PRs that touch core systems to check whether the architecture docs need updating.

Quality

82%

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

Quality

Content

65%

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-organized, actionable guide with concrete principles and Cog-specific facts, but it leans slightly verbose in places and is a monolithic single file rather than using progressive disclosure. Strengthening the audit feedback loop and splitting long factual sections into references would raise the weaker dimensions.

Suggestions

Add an explicit re-validation step to the audit workflow (after fixing structural/misleading issues, re-verify the corrected claims against source before closing).

Tighten the Purpose and "Bridge, don't summarize" sections by trimming the philosophical framing and shortening the Bad code example, which restates code at length.

Move the "Current state of the world" facts and/or the audit checklist into a separate reference file (e.g. CURRENT-STATE.md) and link to it from the body to improve progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The content is mostly efficient and assumes Claude's competence (it does not explain generic concepts, only Cog-specific facts), but the Purpose section and the Good/Bad prose comparison include framing that could be tightened without losing value.	2 / 3
Actionability	For an instruction-only skill the guidance is highly concrete: package-level reference rules with examples, explicit Needs/Doesn't-need update lists, a 4-step audit process, and specific banned phrases — clearly actionable rather than abstract.	3 / 3
Workflow Clarity	The audit workflow is sequenced (read → verify against source → classify → fix) with an explicit verification step, but it lacks a re-validation feedback loop after fixes and checkpoints are largely implicit.	2 / 3
Progressive Disclosure	The single SKILL.md is well-organized into clear sections with no nested references, but at ~115 lines it is monolithic and content such as the "Current state" facts or audit checklist could be split into separate reference files.	2 / 3
	Total	9 / 12 Passed

Description

100%

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 is specific, trigger-rich, and clearly answers both what the skill does and when to use it, with a distinct project-scoped niche. It is a strong, concise description with no notable weaknesses.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — "updating, reviewing, or creating architecture documentation", "auditing docs for accuracy", and "reviewing PRs" — rather than vague language, matching the score-3 anchor.	3 / 3
Completeness	Explicitly states what (update/review/create/audit architecture docs) and when via multiple explicit triggers ("Use this skill when...", "Use it any time...", "Use it proactively when..."), satisfying both halves.	3 / 3
Trigger Term Quality	Covers natural terms a developer would actually say — "refactors", "feature additions", "component changes", "reviewing PRs", "new packages", "build pipeline" — giving good trigger coverage, not just jargon.	3 / 3
Distinctiveness Conflict Risk	Scoped to "architecture documentation in the architecture/ directory" for a specific project (Cog), giving it a clear niche unlikely to conflict with other skills.	3 / 3
	Total	12 / 12 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: replicate/cog
Path: .agents/skills/updating-architecture-docs/SKILL.md
Commit: 4e62b8b

Reviewed: 6 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.