Prompt Engineer

Lint/review agent instruction files. Criteria live only in references/quality-guide.md (do not duplicate them here).

{SKILL_DIR} = directory of this SKILL.md.

Scope

In: SKILL.md, agent .md, CLAUDE.md, protocol
Out: runtime debug, strategy, scaffold from scratch, chat-prompt optimization, model-specific prompt research
Fallback: generic checklist + ask the type

Preconditions

• Target file path from $ARGUMENTS. Нет пути → спроси в чат, не угадывай файл.
• test -f "{SKILL_DIR}/references/quality-guide.md". Нет файла → стоп: «нет references/quality-guide.md».
• test -f "{SKILL_DIR}/scripts/lint_metrics.sh". Нет файла → стоп: «нет scripts/lint_metrics.sh».
• Если вызов из factory – только после validation checkpoint оркестратора.

Algorithm

Step 1: File and type

Path from $ARGUMENTS or ask.

Step 2: Analyze

1. Read references/quality-guide.md – publication DoD + quality criteria + type checklist + anti-patterns. For multi-step / AskQuestion skills also run Workflow Enforcement Patterns.
2. Read the target file.
3. For each criterion: check → severity (critical/major/minor) + a concrete fix (→).
4. Determinism: rigid CLI sequences → suggest moving them to scripts/.
5. Quality criteria (SKILL.md only): clarity, structure, self_containment, safety, preconditions, agent_agnostic, examples, self_improvement – table ✅/❌ + fix.

Metrics script:

"{SKILL_DIR}/scripts/lint_metrics.sh" <file>

Description metrics: character length, : check, trigger phrases, negative triggers – per DoD §Discovery.

Also: compression, anti-patterns table, token estimate (words×1.3), extraction (conditional ≥30 lines → references/).

description_chars из скрипта: major (>400) или critical (>1024) – та же severity в отчёте.

missing_deps из скрипта → major: файл из references/, scripts/ или phases/ назван, но его нет. Оценщик Hub видит только тело SKILL.md, поэтому в теле остаётся сам шаг, в файл уходит длинная процедура.

Step 3: Report

## Prompt Engineer: [file]

**Type:** … | **Size:** ~N tok (~M lines) | **DoD:** Pass/Fail

### Critical / Major / Minor
- [loc]: [issue] → [exact fix text]

### DoD Checklist (SKILL.md)
| Frontmatter | Discovery | Body | Safety | Metrics | → ✅/❌ |

### Quality (SKILL.md)
| clarity | structure | self_containment | safety | preconditions |
| agent_agnostic | examples | self_improvement | → score band |

Score band: 0 critical + ≤2 major → likely 70–85; else likely <60.

### Anti-patterns | What is good | **Grade:** A/B/C/D
A=0 critical ≤1 major | B=0 critical ≤3 major | C=1+ critical

Step 4: Apply

Спроси «Apply? (all / selected / no)». Если нет AskQuestion, тот же вопрос текстом в чат. Правки – точный текст замены.

Step 5: Post-run

If lint found ≥1 major on the quality criteria – propose 1 concrete improvement for prompt-engineer itself. Format: «Gardener: …».

Example

In: «lint SKILL.md – wall of text, path: .agents/skills/foo/SKILL.md»

## Prompt Engineer: foo/SKILL.md
**Type:** SKILL.md | **Size:** ~420 tok (~180 lines) | **DoD:** Fail
### Major
- description: internals instead of triggers → «Use when… Triggers lint, review prompt…»
- body: no ## Example → add a section with input/result
### Quality
| clarity ❌ | examples ❌ | preconditions ❌ | … |
**Grade:** C
Apply fixes? (all / selected / no)

In: «lint agent .agents/agents/cf-publisher.md»

## Prompt Engineer: cf-publisher.md
**Type:** Agent | **Size:** ~200 tok | **DoD:** Fail
### Major
- description: нет when to delegate → «Use when the parent must publish a Confluence page»
**Grade:** C

Hard Stop Rules

• If invoked from a factory pipeline: run only as a Task from the orchestrator; the parent does not lint inline.
• Report before edits
• CLAUDE.md – warn before apply (project-shared)
• Do not change meaning; do not add new content
• : in description – critical

Definition of Done

• Report with severity + DoD checklist + quality table (SKILL.md) + grade shown
• User answered the apply prompt
• Applied fixes = exact text replacements
• Post-run Gardener note if ≥1 major on quality criteria

Check commands

"{SKILL_DIR}/scripts/lint_metrics.sh" <file>
grep -A5 '^description:' <file>   # no ':' in value lines

Gotchas

• A baseline without the guide finds the obvious; value = DoD + quality table + anti-patterns + fix texts
• External quality_score from an evaluator is not replaced by the score band
• preconditions ≠ Hard Stop Rules
• agent_agnostic minor does not block publication
• description >400 major; : critical
• always-on short steps stay in the body; an extracted step is read at entry, not all phases up front
• Use «Trigger phrases …» instead of «Triggers:» in description (avoid :)