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

81%

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

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.

A well-structured, lean guidance skill that gives Claude concrete principles, decision criteria, and an explicit audit workflow. Its main limitation is the absence of an explicit re-verification feedback loop in the audit procedure.

Suggestions

Add an explicit re-verification loop to the auditing workflow (e.g., after fixing structural/misleading issues, re-check the doc against source to confirm the fix holds).

Tighten the Purpose section's philosophical framing to focus purely on actionable guidance, saving a few tokens.

Consider mentioning finer-grained doc operations (splitting, merging, reorganizing) in the description to round out specificity.

Dimension	Reasoning	Score
Conciseness	Lean technical writing that assumes Claude's competence and avoids explaining known concepts; every section earns its place, though the Purpose framing is mildly philosophical and could be trimmed slightly.	4 / 5
Actionability	Provides concrete executable guidance including Good/Bad examples, a practical refactor test heuristic, and decision lists for what does/doesn't need updates; minor gaps exist since it is instructional rather than command-based.	4 / 5
Workflow Clarity	The auditing workflow is a clear 4-step sequence with an explicit verification step ('Verify against source') and a classification checklist plus fix priority, but lacks an explicit re-validate-after-fix feedback loop.	4 / 5
Progressive Disclosure	Well-organized single file with clear sections and subsections and no need for bundle files; it is appropriately self-contained, though at ~120 lines it is not the minimal case that would warrant a 5.	4 / 5
	Total	16 / 20 Passed

Description

87%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, well-targeted description that clearly states what the skill does and gives multiple concrete trigger conditions. It is highly specific to architecture docs and unlikely to fire for unrelated skills.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions ('updating, reviewing, or creating architecture documentation', 'auditing docs for accuracy'), but does not enumerate finer-grained operations like splitting or merging docs that the body covers, so it is not fully comprehensive.	4 / 5
Completeness	Explicitly answers both what ('updating, reviewing, or creating architecture documentation in the architecture/ directory') and when with concrete trigger phrases ('Use this skill when...', 'Use it any time code changes affect how Cog's internals work', 'Also use it proactively when reviewing PRs').	5 / 5
Trigger Term Quality	Includes natural terms users would say ('refactors, feature additions, component changes', 'new packages, changed IPC protocols, modified build pipeline', 'reviewing PRs that touch core systems') with good coverage, but lacks synonyms and file extensions that would push it to 5.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (architecture documentation in the architecture/ directory for Cog's internals) with distinct, specific triggers and minimal overlap risk with other skills.	5 / 5
	Total	18 / 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: replicate/cog
Path: .agents/skills/updating-architecture-docs/SKILL.md
Commit: ec8082f

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