Name: isolating-product-facade-contracts
Rating: 72 (1 reviews)
Author: PostHog

isolating-product-facade-contracts

Plan and execute product isolation migrations to a facade plus contract layer in PostHog, following the Visual review architecture. Use when a product still exposes internals (models/logic/views) across boundaries and needs migration toward contracts.py + facade/api.py + presentation separation, with a PR strategy that minimizes review latency and conflicts with parallel work.

Quality

88%

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

77%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 body is a highly actionable, well-sequenced migration playbook with strong validation feedback loops, but it is over-long for a SKILL.md: the CI-skip rationale is restated across multiple sections and large explanatory tracts that belong in separate reference files are inlined.

Suggestions

Extract the PR strategy, the permanent-interface exception, and the 'Clearing coupling the scan won't show' catalog into reference files (e.g. references/pr-strategy.md, references/permanent-interface.md) and link to them from a leaner SKILL.md overview.

Deduplicate the CI-skip gating rationale: state it once (step 5) and have step 6, the presentation wave, and done criteria back-reference it instead of restating the full reasoning each time.

Tighten the 'No in-process callers' and PR-strategy trade-off prose to the decision and the one-line justification, trimming the repeated 'why this is sound' elaboration.

Dimension	Reasoning	Score
Conciseness	The prose is dense and mostly about non-obvious PostHog-specific domain knowledge Claude lacks, but at ~470 lines it repeats the CI-skip gating rationale (step 5, step 6, presentation wave, done criteria) and re-justifies the 'don't split the facade PR' point, which is more than minor over-explanation.	3 / 5
Actionability	Provides copy-paste-ready commands (hogli product:maturity/lint/isolate:scan/isolate:move, tach check --dependencies --interfaces, lint-imports, git grep) plus concrete file targets, flags (--dry-run), and worked examples (web_analytics, error_tracking, cohorts) covering the common migration cases.	5 / 5
Workflow Clarity	A 6-step sequenced workflow where step 6 is an explicitly dependency-ordered four-step chain enforced by hogli product:lint, with validation checkpoints (--dry-run, tach check, lint-imports, the ignore_imports gate) and error-recovery feedback loops (move refuses on mirrored module → delete shim and repoint, then re-run).	5 / 5
Progressive Disclosure	Section structure is good (## Core docs, ## Guardrails, ## Required migration workflow, ## PR strategy, ## Presentation wave, ## Done criteria) and repo-doc references are clearly signaled one level deep, but no skill-bundle files exist and substantial detail (PR strategy deep-dive, permanent-interface exception, coupling-channel catalog) is inlined in a ~470-line SKILL.md that would benefit from reference files.	3 / 5
	Total	16 / 20 Passed

Description

100%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 is exemplary: third-person voice, concrete actions with named artifacts, explicit what-and-when triggers, and a clearly distinct niche. It matches the top anchor on every dimension without padding or buzzwords.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions with named artifacts — 'product isolation migrations to a facade plus contract layer', 'contracts.py + facade/api.py + presentation separation', and a PR strategy minimizing review latency — giving comprehensive coverage of the migration scope.	5 / 5
Completeness	Explicitly answers both what ('Plan and execute product isolation migrations to a facade plus contract layer in PostHog') and when ('Use when a product still exposes internals across boundaries and needs migration toward contracts.py + facade/api.py + presentation separation') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Comprehensive natural terms a PostHog engineer would actually say, including 'exposes internals (models/logic/views) across boundaries', the concrete filenames (contracts.py, facade/api.py), and 'review latency' / 'conflicts with parallel work'.	5 / 5
Distinctiveness Conflict Risk	Occupies a clear niche — PostHog product isolation to a facade/contract layer following the Visual review architecture — with distinct triggers and minimal overlap risk with other skills.	5 / 5
	Total	20 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 14 suspicious	Warning

	Total	15 / 16 Passed

Repository: PostHog/posthog
Path: .agents/skills/isolating-product-facade-contracts/SKILL.md
Commit: 6fca5f8

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.