CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

principle-separate-before-serializing-shared-state

Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant.

69

Quality

87%

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

SKILL.md
Quality
Evals
Security

Quality

Content

86%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 tight, well-structured principle skill: lean prose, a concrete ownership-split example, named structural serialization mechanisms, and a clear default-then-exception decision flow. The only notable gap is that the serialization option (step 3) is described at the mechanism-name level without a concrete example, unlike the elimination option (step 2).

DimensionReasoningScore

Conciseness

The body is lean and assumes Claude's competence: it never explains what a lockfile or goroutine is, and lines like 'Instructions and conventions are not concurrency control' are maximally dense. The single-sentence 'Why' motivates the pattern without padding, so every token earns its place; level 4's 'minor instances of over-explanation' would require trimmable material that isn't present.

5 / 5

Actionability

Concrete, executable-in-design guidance: 'Give each actor its own owned file, key, branch, or state directory, and merge only at the read/reporting boundary', named serialization mechanisms ('lockfiles, sequential phases, single-writer actor, or atomic compare-and-swap'), and a worked micro-example ('indexer-state.json + metrics-state.json is not'). It stops short of level 5 because the serialization side has no specific example covering its common cases, leaving a minor gap.

4 / 5

Workflow Clarity

A clear 3-step decision sequence (identify shared state → eliminate the shared write target by default → serialize structurally when one shared write target is a real invariant) with an explicit gate ('Treat "we need a lock" as a design smell to check'). It fits 'clear sequence with most checkpoints present; minor validation gaps' — how to verify the invariant is real is left open — better than level 3, where checkpoints would be missing or implicit.

4 / 5

Progressive Disclosure

No bundle files exist (no references/, scripts/, or assets/), and the skill is under 50 lines with no need for external references. Per the simple-skill guideline, the well-organized structure (title, summary paragraph, 'Why', numbered 'Pattern') earns a 5; there is no inlined content that belongs in separate files and no buried references.

5 / 5

Total

18

/

20

Passed

Description

82%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 that explicitly answers both what the skill does and when to apply it, with concrete shared-state trigger objects and a distinctive concurrency niche. Its main weakness is that the action vocabulary is limited to two summary actions and omits common synonyms like 'race condition' or 'merge conflict' that users would naturally say.

Suggestions

Add common natural synonyms users would say, such as 'race condition', 'merge conflict', or 'parallel agents/workers writing', to broaden trigger coverage.

Name one or two more concrete actions or outcomes (e.g., 'split per-actor state files', 'add a lockfile or single-writer phase') to raise action specificity beyond the current two summary actions.

DimensionReasoningScore

Specificity

Names the domain ('concurrent actors might write to the same file, branch, key, or state object') and exactly two concrete actions ('Eliminate the sharing first', 'serialize structurally'), matching the '1-2 concrete actions' anchor rather than level 4's 'several specific actions'. It is well above level 1-2 vagueness since the actions and targets are concrete, not generic.

3 / 5

Completeness

An explicit trigger clause ('Apply when concurrent actors might write to the same file, branch, key, or state object') answers 'when' with concrete conditions, and 'Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant' clearly answers 'what'. Both are explicitly stated with concrete trigger phrases, matching the level 5 anchor; the 'Use when' cap of 3 does not apply.

5 / 5

Trigger Term Quality

Natural trigger terms are present ('concurrent actors', 'same file, branch, key, or state object', 'write'), covering the shared-state target types comprehensively; a few common synonyms are missing ('race condition', 'merge conflict', 'parallel agents/workers'), which fits 'good keyword coverage; a few natural terms missing' rather than level 5, and is better than level 3's 'missing common variations' since four target types are enumerated.

4 / 5

Distinctiveness Conflict Risk

A clear niche (concurrency control for shared mutable state) with distinct triggers ('concurrent actors might write to the same file, branch, key, or state object') that are unlikely to fire for unrelated skills. It is specific enough to avoid the overlap risk described at levels 3-4.

5 / 5

Total

17

/

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

adamsardo/pstack-claude

Path

plugins/pstack/skills/principle-separate-before-serializing-shared-state/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.