grill-this-skill

Files (4)

• SKILL.md
• cspell-words.txt
• promptfooconfig.yaml · evals/
• main.txt · evals/prompts/

SKILL.md (first lines)

# Grill This Skill

Establish enough shared understanding
to safely create or substantially improve an agent skill.
Turn the agreed decisions into an approved skill specification
that later work can use without relying on conversation memory.

Do not use this skill for bounded mechanical edits
that do not change intended behavior, trigger logic, safety constraints, references, or evaluation plans.

## Working style

Ask **one decision at a time**.
For each question:

1. Explain briefly why the decision matters.
2. Offer a recommended default.
3. Wait for the user's answer before asking the next question.

Inspect the repository, existing skill, current specification, references,
and conversation history
before asking about facts that can be discovered.
Challenge vague or contradictory answers without being adversarial.
Adapt technical language to the user's demonstrated experience
and briefly define unfamiliar terms when useful.

## Discovery workflow

### 1. Inspect existing context

Before interviewing, validate any requested skill name against the skill-name rules
and treat it as data rather than a filesystem path.
Then look for:

- the matching skill directory and `SKILL.md` when revising an existing skill;
- the matching specification under `specs/` for the current working agreement;
- relevant material under `specs/references/`;
- conversation history, examples, observed failures, and repository conventions.

If a specification already exists, treat it as the current agreement.
Identify only missing, contradictory, or stale decisions.
Never overwrite it wholesale from conversation memory.

### 2. Resolve the skill's core decisions

Work through these decisions one at a time:

1. **Objective**:
   what outcome should the skill enable?
2. **Audience**:
   who benefits, and what knowledge can the executing agent safely assume?
3. **Style & tone**:
   what communication style follows from that audience?
   Be prescriptive only where consistency, safety, or fragility requires it.
4. **Context**:
   when should the skill trigger,
   and what near misses should not trigger it?
5. **Boundaries & safety**:
   what must the skill not do,
   what authorization is needed,
   and what instructions or sources require caution?
6. **Inputs & outputs**:
   what information does the skill need and what should it produce?
7. **References**:
   what provenance-backed material already exists,
   what candidate URLs or repositories should be researched,
   and what questions remain unanswered?
8. **Evaluation plan**:
   what meaningful behavior should future evaluation distinguish,
   and what evidence establishes the expected result?

Do not treat references or evaluation as optional afterthoughts.
Every approved skill specification needs a lean plan for both.

### 3. Build a lean evaluation plan

Before considering discovery complete, establish:

- the behavior or decision an evaluation should distinguish;
- at least two realistic scenario types, including a near miss when relevant;
- the evidence source for expected behavior;
- whether checks can be objective or need human review;
- whether additional research is required before evaluation design can proceed.

Do not write Promptfoo artifacts or run evaluations in this skill unless the user explicitly asks.
Hand off detailed evaluation work to `develop-skill-evals` when appropriate.

### 4. Record unresolved work honestly

An open decision is acceptable only when it records:

- the unanswered question;
- why it matters;
- what it blocks: authoring, evaluation design, or later refinement; and
- the next owner or handoff.

Do not approve a specification for authoring if an unresolved decision changes the objective, core trigger behavior, or safety boundaries.

### 5. Present the proposed specification

Summarize the decisions in conversation using this structure:

```markdown
# Skill specification example-skill

## Objective

## Audience

### Style & tone

## Context

### Trigger & non-trigger contexts

### Boundaries & safety

## Inputs & outputs

From ibuchanan/agent-skills-toolkit, Apache-2.0.

More from ibuchanan/agent-skills-toolkit