Name: writing-skills
Rating: 68 (1 reviews)
Author: PostHog

writing-skills

Guide for writing PostHog agent skills — job-to-be-done templates that teach agents how to use MCP tools to achieve a goal. Use when adding new product functionality that agents should know how to work with, creating a new skill, or updating existing skills in products/*/skills/.

Quality

83%

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

82%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 meta-skill that respects token budget and gives concrete commands and rules. The main gaps are a missing build/lint failure-recovery loop and no full worked example to imitate.

Suggestions

Add a short feedback loop to the Quick workflow (e.g., 'If lint fails: fix the reported frontmatter/structure issues and re-run hogli lint:skills before building').

Include a minimal complete SKILL.md skeleton (frontmatter + one reference link) so writers have a copy-paste starting template rather than only rules.

Clarify what 'Build to verify' should produce and how to interpret build failures, since that step is the workflow's primary validation gate.

Dimension	Reasoning	Score
Conciseness	Lean body that assumes Claude's competence ('the agent is smart — only include context it doesn't already have'), with every section (workflow, rules, structure, template functions, good/bad examples) earning its place and no basic-concept padding.	5 / 5
Actionability	Provides concrete executable commands (hogli init:skill, lint:skills, build:skills), a precise directory tree, naming rules, and named Jinja2 template functions, but stops short of a full worked SKILL.md example a writer could mirror.	4 / 5
Workflow Clarity	A clear 6-step numbered sequence with explicit verification checkpoints ('Lint', 'Build to verify'), but it lacks an error-recovery feedback loop describing what to do when lint or build fails.	4 / 5
Progressive Disclosure	Well-organized into focused sections and points to one-level-deep resources (the full guide link and the querying-posthog-data example skill); no bundle files ship with this skill, so structure is carried by the entry point alone.	4 / 5
	Total	17 / 20 Passed

Description

83%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-scoped description that clearly states both purpose and activation triggers in third person. Trigger terms are natural and the niche is distinct; only minor gains available in specificity and synonym coverage.

Dimension	Reasoning	Score
Specificity	Names the domain ('writing PostHog agent skills') and lists several concrete trigger actions ('adding new product functionality', 'creating a new skill', 'updating existing skills'), though the core 'what' ('Guide for writing… templates') is slightly abstract, keeping it just below comprehensive.	4 / 5
Completeness	Explicitly answers both what ('Guide for writing PostHog agent skills — job-to-be-done templates that teach agents how to use MCP tools to achieve a goal') and when ('Use when adding new product functionality… creating a new skill, or updating existing skills') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Includes natural phrases a user would say ('creating a new skill', 'updating existing skills', 'adding new product functionality') plus the concrete path 'products/*/skills/', but lacks common synonyms or shorthand variations.	4 / 5
Distinctiveness Conflict Risk	Scoped to a clear niche ('PostHog agent skills', 'products/*/skills/') making it mostly distinct from generic writing skills, with only minor overlap risk against general documentation/coding skills.	4 / 5
	Total	17 / 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: 3 suspicious	Warning

	Total	15 / 16 Passed

Repository: PostHog/posthog
Path: .agents/skills/writing-skills/SKILL.md
Commit: 06292db

Reviewed: 18 minutes 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.