Video summary

Building Great Agent Skills: The Missing Manual

Main summary

Key takeaways

Technology

The Argument: “Skill Hell” Is the Next Problem

The video argues that the next “developer hell” is skill hell: people download many agent “skills” (tools/prompts) but can’t tell which ones are good vs. bad, or how to combine them reliably. The result is weak performance at both:

  • the individual level, and
  • the organization level.

The Proposed Solution: A “Missing Manual” Skill Checklist

The speaker proposes a checklist/rubric for evaluating and improving skills, plus a reference implementation they claim is encoded in a repo.

The checklist has four parts.

1) Trigger (How the Skill Is Invoked)

Skills can be invoked in two main ways:

  • User-invoked: the user calls the skill; the agent may not have the skill description available.
  • Model-invoked: the agent decides to call the skill using the skill description in its context.

Key trade-offs:

  • Model-invoked skills add agent context load (token cost + more content for the agent to reason about).

  • User-invoked skills add user cognitive load, but can improve reliability and reduce unpredictability.

  • Unpredictability risk (model-invoked): the model may not follow a context pointer at the right time.

Tip 1: Decide whether a skill should be user-invoked or model-invoked based on:

  • context load,
  • cognitive load, and
  • reliability.

2) Structure (Internal Layout of a Skill)

The speaker suggests most skills are made of two units:

  • Steps: the step-by-step procedure
  • Reference: supporting docs/templates

To keep skills maintainable and cheaper to run, the speaker emphasizes keeping skill.md as small as possible.

Branching/scenario-specific reference via context pointers

To avoid clutter in the main skill file, branch-only material should be placed behind context pointers (external markdown files referenced from skill.md).

This reduces clutter while still bundling the needed docs with the skill package.

Examples:

  • A skill like “two PRD” uses a small number of steps plus reference (e.g., “what is a test seam” and a PRD template).
  • A more branched skill like domain modeling can move templates (ADR/context) into external references.

3) Steering (Making the Agent Do What You Intend)

Core technique: “leading words” (referred to as “lightvert” in subtitles; conceptually similar to using a strong repeated keyword/phrase).

How leading words work

  • Insert a deliberately meaningful phrase into the skill text (e.g., “vertical slice”).
  • The agent repeats/uses the phrase in its reasoning/output, which “steers” behavior toward the intended approach.

Example: Agents often implement work layer-by-layer. Using “vertical slice” encourages planning/implementation as thin vertical slices. The speaker also suggests you can verify success via reasoning traces.

Another steering lever: force more “leg work” per phase

If the agent rushes to the final goal (e.g., in “plan mode”), restructure so it only sees the current step.

Example flow:

Instead of a plan-mode flow that:

1) asks clarifying questions, then 2) creates a plan in one place,

the speaker uses separate skills:

  • “grill with docs” for clarifying questions
  • then “two PRD” to proceed after docs are gathered

Goal: prevent skipping deep investigation.

4) Pruning (Failure-Mode Cleanup to Reduce Bloat and Errors)

A final pass should remove common problems:

  • Massive skills (often caused by other issues)

  • Duplication: ensure each piece has a single source of truth (don’t repeat templates/concepts across multiple places)

  • Sediment: uncontrolled growth of shared docs (stale/irrelevant material)

  • No-ops: instructions that look meaningful but don’t actually affect behavior (e.g., deleting a paragraph about commit message length doesn’t change output)

The speaker mentions techniques like deletion tests to detect no-ops and keep skills small.

How to Start / Productization Guidance

  • The speaker claims all checklist items are implemented in a new skill in their repo called “writing great skills”.
  • Suggested workflow:
    • Use that skill to improve your own skills
    • Potentially audit community-authored skills for quality
  • Mentions a broader plan:
    • a newsletter and an AI coding crash course.

Main Speakers / Sources Mentioned

  • Primary speaker: the creator/maintainer of Matt PCO / “Matt Pot” skills and the referenced repos:

    • “mattpco skills”
    • “writing great skills”

  • Named systems for comparison (not speakers):

    • “Superpowers” (described as a popular set of primarily model-invoked skills)

Original video