working-with-skills

Guides agents in discovering, authoring, and updating PostHog skills via MCP skill-* tools.

713|118|Updated Aug 11, 2020
One-click install
npx skills add https://github.com/PostHog/posthog-foss --skill working-with-skills
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: working-with-skills
Source: https://github.com/PostHog/posthog-foss/tree/main/products/skills/skills/working-with-skills
Command: npx skills add https://github.com/PostHog/posthog-foss --skill working-with-skills

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Agents managing PostHog skills through the MCP skill-* tools often waste context, make redundant round-trips, or corrupt skills by choosing the wrong write primitive. This Skill provides the decision tree, efficiency rules, and pitfall guidance needed to discover, read, create, update, and archive skills correctly—especially large skills with many bundled files.

Core Features & Use Cases

  • Tool selection decision tree: Maps every task (discover, read, create, edit body, patch files, rename, archive) to the correct skill-* tool with the smallest appropriate write primitive.
  • Progressive disclosure workflow: Enforces lazy loading—list descriptions first, fetch one body per task, and pull bundled files only when the body references them.
  • Concurrency-safe writes: Explains base_version optimistic locking, chaining versions across sequential writes, and recovering from 409 conflicts.
  • Use Case: An agent asked to fix a typo in a skill's bundled script uses skill-get to capture the version, then a single skill-update with file_edits instead of round-tripping the entire bundle—producing one clean, reviewable version.

Quick Start

Ask the agent to update an existing PostHog skill's body or bundled files using the smallest appropriate skill-* tool with a valid base_version.

Frequently Asked Questions about working-with-skills

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I update a PostHog skill without replacing the whole bundle?

Use skill-update with the edits parameter for body changes or file_edits for patching existing bundled files. These targeted primitives avoid round-tripping the entire skill and keep version history readable. Passing files to skill-update replaces the whole bundle and should be reserved for full reseeds.

How do I choose between the skill-* MCP tools?

Use skill-list for discovery, skill-get for one body plus file manifest, and skill-file-get for individual files on demand. For writes, use skill-create for new skills, skill-update with edits or file_edits for changes, and the per-file create, delete, and rename tools for structural changes.

What is base_version and why do skill writes fail without it?

base_version is an optimistic concurrency token accepted by every skill write tool. The server compares it to the latest version and rejects the write if they differ, preventing silent overwrites. Capture it from skill-get or the previous write response and chain it through sequential edits.

When should I use file_path versus path in skill tools?

file_path is used when the path travels in the URL, specifically skill-file-get and skill-file-delete. path is a body field used by skill-file-create, the files array, and file_edits, while skill-file-rename uses old_path and new_path. Mixing them up causes 404 errors.

When is archiving a skill appropriate and can it be undone?

skill-archive hides every active version of a skill by name and cannot be undone, removing it from skill-list and skill-get for the whole team. Use it only to retire a skill entirely; for removing one file use skill-file-delete, and for rollbacks publish a new version instead.