Analyzing the grill‑me Agent Skills Repository: Making Probabilistic LLMs Deterministic

Core Principles of Skills

Atomic : each skill solves a single, well‑defined problem.

Editable : skills are copied into the project, encouraging forking and local modification.

Composable : skills are linked with the /skill syntax instead of a monolithic state machine.

Human‑controlled : critical steps must be triggered by a person; the model cannot act autonomously.

Four Repeated Failure Types and Their Remedies

Unclear or Misaligned Requirements : use a “grilling” phase to bridge the gap. Run /grill-me when no codebase exists or /grill-with-docs when a repository is present. Record the dialogue in CONTEXT.md and ADR files.

Lack of Shared Language : create a project‑specific glossary ( CONTEXT.md) to replace verbose descriptions with precise terms.

Slow Feedback / Broken Code : adopt a TDD loop ( /tdd) and a bug‑diagnosis skill ( /diagnosing-bugs) that run type checks, incremental tests, and isolated commands before each change.

Design Drift : insert design reminders via /to-spec, /codebase-design, and /improve-codebase-architecture to keep modules “deep” and avoid uncontrolled rewrites.

Repository Structure

skills/ – all skill definitions, grouped by directory.

docs/ – human‑readable documentation (engineering / productivity).

.claude-plugin/ – Claude plugin manifest and marketplace entry.

.agents/ – Agent maintenance contracts, trigger rules, ADRs.

scripts/ – helper scripts such as link-skills.sh and list-skills.sh.

CLAUDE.md / AGENTS.md – agent rules; AGENTS.md is a symlink for Codex.

CONTEXT.md – project‑specific domain glossary.

package.json – private package metadata (mostly Changesets).

.changeset/ + release.yml – versioning and release workflow.

.out-of-scope/ – explicitly excluded responsibilities to prevent scope creep.

Skill Layout Example

skills/<bucket>/<skill-name>/

SKILL.md

– YAML header + steps / references. agents/openai.yaml – Codex interface and implicit‑call strategy. *.md / scripts/ – optional docs or script templates.

Example: the writing-great-skills skill splits terminology into GLOSSARY.md.

Invocation Rules

Skills are divided by who can trigger them:

User‑invoked : only manual /xxxxx commands; description is a human‑readable one‑line summary; cost is remembering the command; cannot be called by other skills.

Model‑invoked : can be triggered by human or model; description is a model‑readable trigger phrase; each invocation consumes a conversation turn; callable by other skills.

Claude disables model‑invocation with disable-model-invocation: true; Codex uses policy.allow_implicit_invocation: false. Slash‑style calls ( /grilling) forbid cross‑directory deep links such as ../other-skill/FILE.md.

Main Flow (Five Steps)

grill‑with‑docs : clarify the task, populate CONTEXT.md and ADRs.

to‑spec : consolidate the clarified intent into a spec; no further questioning.

to‑tickets : break the spec into independent “tracer‑bullet” tickets, each with a clear blocker.

implement : execute each ticket using the /tdd loop (type checks, incremental tests, final full run).

code‑review : auto‑triggered before commit; checks coding standards (Fowler’s code‑smell list) and requirement compliance, surfacing refactoring needs separate from the TDD cycle.

Additional Entry Points

/triage

: turn a backlog of issues into Agent‑ready tickets. /diagnosing-bugs: run a failing command, add logs, and fix. /improve-codebase-architecture: periodically scan for modules that need to become “deep”. /wayfinder: for large, ill‑defined problems, build a visible map of dependencies, then return to /to-spec (never jump straight to /implement). /to‑tickets output is already actionable; do not feed it back into /triage.

Reference Skills

/domain-modeling

: refine domain language, add edge‑case terms, write ADRs. /codebase-design: provide terminology for module design (module, interface, depth, seam, adapter). /grill-with-docs: drives /domain-modeling as the primary entry.

Wayfinder Details

Creates a shared map of tasks with tags indicating who must act:

Research (AFK) : Agent fetches docs, APIs, internal knowledge via /research.

Prototype (HITL) : Human builds a throw‑away prototype to visualise ideas.

Grilling (HITL) : One‑question‑one‑answer sessions requiring human approval before code is written.

Task (HITL or AFK) : Operational steps (service registration, data migration) that block downstream decisions.

Crafting a Skill – Guidelines

Order content by immediacy: execution steps first, reference material later.

Pick a familiar trigger word that conveys the whole behaviour (e.g., “red” for a failing test).

Name common failure modes so they can be referenced and reviewed.

Typical failure‑mode patterns and handling:

Premature completion : tighten completion criteria.

Duplication : keep a single source of truth.

Sediment : regularly prune accumulated cruft.

Sprawl : move references out, split by branches.

No‑op : delete if the model would do it automatically.

Negation : re‑phrase prohibitions as positive goals.

Negative Space : make every silence intentional.

Setup Skill

The one‑time /setup-matt-pocock-skills skill prompts the Agent to understand the project (remote URL, existing CLAUDE.md / AGENTS.md / CONTEXT.md, presence of .scratch/, monorepo status) and then writes configuration files such as docs/agents/issue-tracker.md, domain.md, and triage-labels.md. Hard dependencies ( /to-spec, /to-tickets, /triage) require this setup; soft dependencies ( /tdd, /diagnosing-bugs) work without it but are less precise.

Installation

Typical command: npx skills add mattpocock/skills Comparison:

skills.sh : copied into the project, editable; suited for users who want to modify or localise.

Claude plugin : read‑only, updated with each version; suited for users who want a ready‑made set.

Note: v1.1 renamed many skills; reinstall and verify removal of old names such as to‑prd, to‑plan, to‑issues.

Limits and Risks

Popularity does not guarantee a silver bullet; model updates can break assumptions.

Rules like disable-model-invocation rely on runtime enforcement.

Human‑only confirmation steps can be bypassed by the model if not strictly enforced.

Token cost for a full end‑to‑end run is non‑trivial; small edits should avoid the full pipeline.

Concurrent Agents writing to .scratch/ lack locking, risking conflicts in multi‑person teams.

Conclusion

Human decisions remain irreplaceable, but they can be packaged into repeatable, composable, and improvable skill bundles. Effective Agent‑assisted development hinges on knowing when to clarify requirements, draw a map, or provide feedback. The repository’s patterns—clear invocation boundaries, shared vocabularies, named failure modes, and modular design—are transferable to any project.