AGENTS.md · diff
git:20260822.cf4a48b to git:20260824.49ceb03
657 added, 112 removed. Audit A to A.
- # AGENTS.md
+ # SKILL-SPEC.md
+ ## Product Marketing Skills — Skill Authoring Standard
- Guidelines for AI agents working in this repository.
+ **Version:** 2.3.0
+ **Last updated:** 2026-08-24
+ **Applies to:** All skills in this repository
+ **Owner:** Stefanos Karakasis
- ## Repository Overview
+ This is the canonical standard every skill in this repo must meet.
+ The `meta-review` skill enforces it. New skills ship only when they pass it.
+ There is no separate improvement-schedule document — this spec itself is
+ the record of what's required, and it's updated in place as standards change.
- This repository contains **PMM Skills** for AI agents following the
- [Agent Skills specification](https://agentskills.io/specification.md).
- This repo also serves as a **Claude Code plugin marketplace** via
- `.claude-plugin/marketplace.json`.
+ ---
- - **Name**: Product Marketing Skills
- - **GitHub**: [stefanoskarakasis/Product-Marketing-Skills](https://github.com/stefanoskarakasis/Product-Marketing-Skills)
- - **Creator**: Stefanos Karakasis
- - **License**: MIT
+ ## 1. What a Skill Is (and Isn't)
- ## Repository Structure
+ A skill is a **structured instruction set** that tells Claude how to behave when invoked. It is not documentation, a feature list, or a README.
- ```
- Product-Marketing-Skills/
- ├── .claude-plugin/
- │ ├── marketplace.json # Claude Code plugin marketplace manifest
- │ └── plugin.json # Root plugin manifest
- ├── product-marketing-context/ # The brain — pmm-foundation plugin
- ├── pmm-go-to-market/ # Go-to-market strategy + workflow orchestration
- ├── pmm-positioning/ # Positioning & messaging
- ├── pmm-execution/ # Day-to-day PMM execution
- ├── pmm-toolkit/ # PMM utilities
- ├── pmm-meta/ # Meta skills (skill quality, learning, verification)
- ├── context/ # Guardrails: meta-patterns.md, read by every skill's pre-flight
- ├── CONTRIBUTING.md
- ├── SKILL-SPEC.md # Skill authoring standard
- ├── LICENSE
- ├── README.md
- ├── QUICK-START.md
- ├── CHANGELOG.md # Repo-wide release log — see Versioning below
- └── AGENTS.md # AI agent guidelines
- ```
+ A skill that reads like a README produces README-quality output.
+ A skill that reads like an operating manual produces operating-manual-quality output.
+ **The test:** Could a new PMM follow this skill and know exactly what to do at every step, in every edge case, without asking a question? If no — it's not done.
- ## Build / Lint / Test Commands
+ ---
- Skills are content-only (no build step). Verify manually:
- - YAML frontmatter is valid
- - `name` field matches directory name exactly
- - `name` is 1-64 chars, lowercase alphanumeric and hyphens only
- - `description` is 1-1024 characters
- - Brain-dependent skills read from `/foundation/brain.md` for shared context
+ ## 2. File Structure
- ## Agent Skills Specification
+ Every skill lives in its own directory:
- Skills follow the [Agent Skills spec](https://agentskills.io/specification.md)
- and this repo's own [SKILL-SPEC.md](SKILL-SPEC.md), which is the canonical
- authoring standard for this repo specifically.
+ ````
+ skills/skill-name/
+ ├── SKILL.md ← Required. Main instruction file. Max 500 lines.
+ ├── evals/
+ │ └── skill-name.eval.md ← Required. At least 3 test cases.
+ ├── config/ ← Optional. Reference data, frameworks, defaults.
+ └── templates/ ← Optional. Output templates, examples.
+ ````
- ### Required Frontmatter
+ **Hard rules:**
+ - `SKILL.md` stays under 500 lines. Move reference material to `config/` or `references/`.
+ - Directory name must exactly match the `name` field in frontmatter.
+ - `evals/` is not optional. A skill without evals has no quality floor.
+ - **Do not have a `SKILL.md` in a template folder** — Claude Code treats any file named `SKILL.md` as a loadable skill.
+ - **Do not create `config/`, `memory/`, or `templates/` directories to hold a skill's own session log, state, or scheduler.** The compounding mechanism is centralized — see Section 5.1. A per-skill directory for this purpose duplicates it and drifts.
- ```yaml
---
+
+ ## 3. Frontmatter — Required Fields
+
+ Every `SKILL.md` opens with YAML frontmatter:
+
+ ````yaml
+ ---
name: skill-name
- description: What this skill does and when to use it. Include trigger phrases.
+ version: 1.0.0
+ description: >
+ What this skill does + 3–5 trigger phrases verbatim. Target 300–600 chars.
+ Trigger phrases belong here — they drive auto-fire. Explanatory prose
+ belongs in the H1 paragraph of the body, not here.
+ Example: "Assigns launch tier and builds GTM strategy briefs. Trigger on:
+ 'launch this', 'what tier is this', 'GTM strategy for', 'run GTM workflow'."
+ metadata:
+ author: Stefanos Karakasis
+ context: brain-dependent # or: context-agnostic — see Section 8
+ quality_gate: true # false only for simple utilities
+ last_updated: YYYY-MM-DD
---
- ```
+ ````
- ### Name Field Rules
+ ### Field rules
- - Lowercase letters, numbers, and hyphens only
- - Cannot start or end with hyphen
- - No consecutive hyphens (`--`)
- - Must match parent directory name exactly
+ | Field | Required | Rule |
+ |---|---|---|
+ | `name` | Yes | Lowercase, hyphens only. Matches directory name exactly. No `--`. |
+ | `version` | Yes | Semantic versioning. See Section 10. |
+ | `description` | Yes | 300–600 chars. Trigger phrases verbatim. Mention related skills for scope boundaries. |
+ | `metadata.author` | Yes | Author name. |
+ | `metadata.context` | Yes | `brain-dependent` or `context-agnostic`. See Section 8. |
+ | `metadata.quality_gate` | Yes | `true` for any skill producing strategic output. `false` for simple utilities only. |
+ | `last_updated` | Yes | ISO date of last meaningful change. |
- **Known exception in this repo today:** the `experiment-doc` skill folder
- has a `name:` field of `experiment-doc-builder` in its frontmatter, which
- doesn't match the folder name. Structure resolution in this repo is by
- directory (via each plugin's `plugin.json` `"skills"` pointer), not by the
- frontmatter `name:` field, so this doesn't break anything functionally —
- but it should still be fixed to match exactly. No other skill in the repo
- currently has this mismatch.
+ ---
- ## Brain Integration
+ ## 4. The Seven Required Sections
- Brain-dependent skills read from `/foundation/brain.md` — a shared context
- layer built by the `product-marketing-context` skill. It has exactly 6
- sections: Product Context, ICP Definition, Alternatives & Positioning,
- Voice & Tone, Market Context, and Proof Points Registry. There is no
- Section 7 — earlier drafts of several skills invented one (variously
- called "Strategy Layer," "Launch History," or "Meta-Learnings") and every
- instance found has been removed. If you see a skill reference a brain
- Section 7, that's a bug — file it or fix it, don't treat it as real.
+ Every `SKILL.md` must contain exactly these seven sections, in this order. **Do not rename them. Do not omit them.** Use `n.v.t.` if a section doesn't apply — that's the whole point. An omitted section says nothing. `n.v.t.` says "I considered this and it doesn't apply."
- **Status:** every skill's brain-read/write claims have been verified
- against this 6-section schema as of Workstream 4b. If a skill you're
- touching cites a section number that doesn't match this list, treat that
- as a bug in the skill, not in this document.
+ After frontmatter, open with:
- When using brain-dependent skills, ensure `/foundation/brain.md` exists.
- If not, run `product-marketing-context` to build it.
+ ````markdown
+ # Skill Name
- ## Claude Code Plugin
+ One paragraph. What this skill does and why it exists. No commands, no section
+ headers — just the essence. Someone reading this paragraph should know immediately
+ whether this is the right skill.
+ ````
- This repo serves as a plugin marketplace via
- `.claude-plugin/marketplace.json`, listing six plugins:
+ Then the seven sections:
- ```bash
- claude plugin marketplace add stefanoskarakasis/Product-Marketing-Skills
- claude plugin install pmm-foundation
- claude plugin install pmm-go-to-market
- claude plugin install pmm-positioning
- claude plugin install pmm-execution
- claude plugin install pmm-toolkit
- claude plugin install pmm-meta
+ ---
+
+ ### Section 1: `## Trigger`
+
+ When to use this skill and when not to. Explicit routing to other skills.
+
+ ````markdown
+ ## Trigger
+
+ - **When:** The condition that fires this skill. One sentence.
+ - **Not for:** Explicit exclusions — prevents scope creep and overlap.
+ Reference the correct skill by name.
+ - **Example prompts:**
+ - "exact trigger phrase 1"
+ - "exact trigger phrase 2"
+ - "edge case phrasing that should also work"
+ ````
+
+ **Why this matters:** Without explicit exclusions, skills accumulate scope silently. After 10 skills, nobody knows where one ends and another begins. Name the boundary.
+
+ ---
+
+ ### Section 2: `## Inputs`
+
+ What this skill needs before it can run.
+
+ ````markdown
+ ## Inputs
+
+ - **Args:** What the user passes. CLI-style if applicable. `n.v.t.` if none.
+ - **Defaults:** What happens if no arg is given. `n.v.t.` if no defaults.
+ - **Context keys:** Which files, brain sections, or external resources are
+ needed before running. List file paths explicitly.
+ n.v.t. if context-agnostic and no files needed.
+ ````
+
+ ---
+
+ ### Section 3: `## Pre-flight`
+
+ Dependency checks and early-exit conditions. Running before anything else.
+
+ ````markdown
+ ## Pre-flight
+
+ - [Dependency check — what must exist or be loaded]
+ - [Early-exit condition — when failing fast beats degraded output]
+ - n.v.t. if no pre-flight needed — write it explicitly, don't omit it.
+ ````
+
+ **The `n.v.t.` rule applies here most often.** Simple utility skills genuinely have no pre-flight. Write `n.v.t.` explicitly so reviewers know it was considered.
+
+ ---
+
+ ### Section 4: `## Steps`
+
+ The core logic. Each step is a discrete, named action.
+
+ **Step header convention:** Always include a short name in imperative form.
+
+ ````markdown
+ ## Steps
+
+ ### Step 1: Load Context
+
+ [Action. Concrete. What to read, what to extract.]
+
+ ### Step 2: Run Intake
+
+ [Next action.]
+
+ ### Step N: Deliver Output
+
+ [Closing action.]
+ ````
+
+ **Why named steps matter:** Cross-references in memory files and knowledge logs use step names. If you renumber steps, names keep references stable. `"See Step 4 (Intake)"` survives a re-order. `"See Step 4"` doesn't.
+
+ Rules for steps:
+ - Each step has one job. Split if a step does two things.
+ - Use code blocks for commands, queries, output templates.
+ - Use `> ⚠️` callouts for rules that cannot be skipped. Use sparingly — if everything is urgent, nothing is.
+ - Idempotent where possible.
+
+ **For T1/T2 skills, the last step is always Learning Close** — see Section 5.1. It is a Step, not a separate section, and it is not optional.
+
+ ---
+
+ ### Section 5: `## Outputs`
+
+ What this skill produces.
+
+ ````markdown
+ ## Outputs
+
+ - **Files written:** path → what's in it. n.v.t. if pure read-only.
+ - **Chat output format:** markdown shape, with example or reference to
+ example in appendix. n.v.t. if no chat output.
+ - **External side effects:** DB writes, external services triggered.
+ n.v.t. if none.
+ ````
+
+ **Convention — output templates go in a code fence.** If this section or an appendix shows a template with H2/H3 headers, wrap it in ` ```markdown … ``` `. Otherwise every parser (skill audit, plugin sync) reads those raw `##` lines as skill sections — producing broken audits.
+
+ **For T1/T2 skills:** list `/context/skill-sessions.md` under **Files written** — one appended row per session, per the Learning Close step (Section 5.1). This is a small, structured write, distinct from any file the skill asks the user's permission to save output to.
+
+ ---
+
+ ### Section 6: `## Verification`
+
+ How to confirm the skill ran correctly. Concrete and checkable.
+
+ ````markdown
+ ## Verification
+
+ - [How to verify the output is correct. Concrete commands or checks.]
+ - [What the expected result looks like.]
+ - n.v.t. only if the output is self-evidently verifiable with no steps needed.
+ ````
+
+ This is not a quality gate (that's in Section 9). Verification is for the user to confirm success after the skill completes.
+
+ ---
+
+ ### Section 7: `## Do Not Use For`
+
+ Explicit routing away from this skill. Every skill has boundaries.
+
+ ````markdown
+ ## Do Not Use For
+
+ - **skill-name** — When to use that skill instead. One sentence.
+ - **skill-name** — When to use that skill instead.
+ - n.v.t. if this skill has no overlap with other skills — write it explicitly.
+ n.v.t. here means: "overlap was considered and there is none."
+ ````
+
+ **This is the most important section for a multi-skill system.** Without it, users hit the wrong skill and get confused. With it, the routing is baked in.
+
+ ---
+
+ ## 5. Additional Required Sections (Strategic Skills)
+
+ For Tier 1 and Tier 2 skills (see Section 12), add these after the seven required sections:
+
+ ### `## Operating Rules`
+
+ Non-negotiable rules for this skill. One rule per line. These are what `verify` checks against.
+
+ ````markdown
+ ## Operating Rules
+
+ - **Rule statement.** Reason or consequence.
+ - **Rule statement.** Reason or consequence.
+ ````
+
+ Minimum 6 rules for T1/T2 skills. If you can't write 6, the skill doesn't have enough defined behaviour to be production-grade.
+
+ ### `## Quality Gate`
+
+ Runs after output generation, before delivery. Required for all skills where `quality_gate: true`.
+
+ ````markdown
+ ## Quality Gate
+
+ Runs after output generation. Surface failures before delivering — never after.
+
+ | Check | Standard | Pass = |
+ |---|---|---|
+ | [Check name] | [What it tests] | [Pass condition] |
+ ````
+
+ Minimum 5 checks. Each check must be binary (pass/fail), not subjective.
+
+ **For T1/T2 skills, include a Learning Close row** — see Section 5.1's template block, which has the exact row to copy.
+
+ ### 5.1 `## Self-Improvement Loop` — required for T1/T2 (v2.2.0)
+
+ **As of v2.2.0 of this spec, every T1/T2 skill's `## Steps` section must
+ end with a Learning Close step, copied verbatim from the template below.**
+ This reverses the v2.1.0 position, which correctly removed a fabricated
+ per-skill promotion pipeline (`knowledge/rules.md`, `knowledge/hypotheses.md`,
+ a "confirmed 3+ times" graduation rule) that never actually ran anywhere in
+ this repo. That removal was correct. What's below is not a return to that —
+ it's the first real, working version, deliberately small.
+
+ **Why a template, not per-skill prose:** Operating Rules and Quality Gate
+ already work this way — defined once, copied by every skill, not
+ reinvented per file. A skill added a year from now copies the same block
+ everyone else did; nobody has to remember the "right" wording. Hand-authoring
+ equivalent logging prose into each skill individually is the same
+ per-file-drift failure mode this spec exists to prevent — so this section
+ gives the one block to copy, not a description to reimplement.
+
+ **Copy this block verbatim as the final step in `## Steps`, renumbered to
+ fit the skill's own step count:**
+
+ ````markdown
+ ### Step [N] — Learning Close
+
+ End every completed session by appending one row to `/context/skill-sessions.md`
+ (create the file with a header row if it doesn't exist yet):
+
+ ```yaml
+ skill: [this skill's name]
+ session_date: [YYYY-MM-DD]
+ pattern: [one falsifiable statement about what happened this session, or "none"]
+ source: [surprised / wrong / missing / n.v.t.]
```
- See [Claude Code plugins documentation](https://docs.claude.ai/plugins)
- for details.
+ Write this row directly — do not ask the user for permission. This is an
+ observational log entry, not a content write to `/foundation/brain.md` or
+ `/context/meta-patterns.md`, which still require explicit approval elsewhere
+ in this skill or in `meta-synthesis`. If nothing notable happened this
+ session, still write the row with `pattern: none` — a consistent log beats
+ a sparse one `meta-synthesis` can't trust.
+ ````
- ## Git Workflow
+ **Add this Quality Gate row** (exact wording, adjust only the table's own column style to match the skill's existing table):
- ### Branch Naming
+ ````markdown
+ | Learning Close ran | `/context/skill-sessions.md` has a new row for this session | Yes |
+ ````
- - New skills: `feature/skill-name`
- - Improvements: `fix/skill-name-description`
- - Documentation: `docs/description`
+ **What this replaces:** Any existing line asking the user where, if
+ anywhere, to save a pattern or note before close (several T1/T2 skills
+ carried a version of this after Workstream 4b removed the old fabricated
+ pipeline). Replace that line with the Learning Close step above — do not
+ keep both. The one-row log is not a substitute for the skill's own output
+ (a brief, a brain update, a PRD) — those still get delivered and saved
+ exactly as the skill's own `## Outputs` section already describes.
- ### Commit Messages
+ **What this does not change:** `meta-learn` remains the deliberate,
+ on-demand deep-dive tool — the three-question interview (surprised / wrong
+ / missing) for a session that deserves more than a one-line row. It is no
+ longer the only path to `/context/skill-sessions.md`; Learning Close covers
+ every T1/T2 session automatically, and `meta-learn` covers the sessions
+ worth a closer look. Both write to the same file in the same format, so
+ `meta-synthesis` reads one consistent log regardless of which produced
+ each row.
- Follow the [Conventional Commits](https://www.conventionalcommits.org/)
- specification: `feat: ...`, `fix: ...`, `docs: ...`.
+ **T3 and T4 skills:** Learning Close is not required. T3 utility skills are
+ low-stakes and high-frequency enough that a log row per run would be mostly
+ noise; T4 meta-skills operate on other skills, not on GTM outcomes, and
+ several already write their own session metadata to the same file for
+ different reasons (see `meta-synthesis`'s own Step 4). A T3 or T4 skill may
+ add Learning Close if the author judges it useful, using the same template.
- ### Pull Request Checklist
+ ### `## Changelog` — not required
+ **As of v2.1.0 of this spec, no skill should have a `## Changelog`
+ section.** Version history belongs in this repo's git log, which is
+ the actual audit trail — a hand-maintained changelog duplicates it,
+ drifts from it, and was removed from every `SKILL.md` in the repo
+ across Workstream 4b. `metadata.last_updated` in frontmatter is
+ sufficient for "when did this last change" at a glance.
+
+ ---
+
+ ## 6. Appendix Conventions
+
+ Optional content goes after the seven required sections. Use these canonical appendix names so skill-audit tooling can skip them correctly:
+
+ | Appendix name | Use for |
+ |---|---|
+ | `## Gotchas` | Edge cases, traps, knowledge that doesn't follow from the steps |
+ | `## Voice reference` | Link to voice/tone reference file |
+ | `## Example output` | Reference illustration of what the skill produces |
+ | `## Edge cases` | Optional, with suffix if needed: `Edge cases — delivery` |
+ | `## When to offer proactively` | When Claude should suggest this skill unprompted |
+ | `## Dialog mode` | Opt-in conversational behaviour for iterative skills |
+ | `## Reference` | External docs, links |
+
+ **Binding appendices** — those that are part of the flow, not just reader notes — get `(appendix — reference for Step N)` in the title. Example: `## Feedback format (appendix — reference for Step 8)`. This makes it visible that the appendix is part of the execution path.
+
+ ---
+
+ ## 7. The `n.v.t.` Rule
+
+ This is the single most important consistency mechanism in the spec.
+
+ **Every section must be present. Always.**
+
+ If a section doesn't apply to a skill, write `n.v.t.` (not applicable) under it — do not omit the section.
+
+ - An omitted section says nothing about whether it was considered.
+ - `n.v.t.` says: "this was considered and doesn't apply."
+
+ These are completely different signals. The second is auditable. The first is not.
+
+ **This rule applies to all seven required sections and to the `## Do Not Use For` section specifically.** A `## Do Not Use For` with `n.v.t.` says: "there are no overlapping skills." A missing `## Do Not Use For` says nothing — and after 15+ skills, that silence causes real confusion.
+
+ ---
+
+ ## 8. Context Classification: Brain-Dependent vs Context-Agnostic
+
+ The most important architectural decision for each skill. Declared in frontmatter as `metadata.context`.
+
+ ### Brain-Dependent (`brain-dependent`)
+
+ Must load `/foundation/brain.md` before running. Output depends on company-specific ICP, positioning, alternatives, voice, or proof points.
+
+ Load instruction for brain-dependent skills:
+
+ ````markdown
+ ## Pre-flight
+
+ - Load `/foundation/brain.md`. Extract: [Section X → what to pull and why].
+ - If brain file missing: surface once, non-blocking:
+ > "No PMM context found. Run `product-marketing-context` to make this
+ > significantly sharper. Continuing with assumption-based output."
+ - If a loaded section is marked 🔴 Placeholder: flag before proceeding.
+ ````
+
+ **Brain-dependent skills:** `positioning-messaging`, `go-to-market-strategy`, `gaccs-brief`, `stakeholder-maps`, `retro`, `pre-mortem`, `workflow-orchestrator`, `pmm-okrs`, `beachhead-segment`, `product-marketing-context`
+
+ ### Context-Agnostic (`context-agnostic`)
+
+ Must **not** load brain context. Operates on universal frameworks and the user's input only.
+
+ Load instruction for context-agnostic skills:
+
+ ````markdown
+ ## Pre-flight
+
+ - This skill is context-agnostic. Do not load `/foundation/brain.md`.
+ - Do not apply prior company context, ICP, or positioning assumptions.
+ - Start from the user's input only.
+ ````
+
+ **Why this matters:** If `experiment-doc` loads your current ICP, it validates experiments that fit your current ICP instead of stress-testing them. The framework must be objective.
+
+ **Context-agnostic skills:** `experiment-doc`, `prioritization-frameworks`, `privacy-policy`, `pmm-resume`, `writing-assistant`, `interview-summary`, `prd`
+
+ **The rule:** If output quality depends on knowing your product → brain-dependent. If output quality depends on a universal framework → context-agnostic. When in doubt, choose agnostic.
+
+ ---
+
+ ## 9. Brain Read/Write Contract
+
+ For every brain-dependent skill, declare exactly what it reads and writes. Add this block to `## Inputs`:
+
+ ````markdown
+ **Brain contract:**
+ - Reads: Section 2 (ICP) — [what specifically], Section 3 (Positioning) — [what specifically]
+ - Writes: Section 2 (ICP) — [what is written and when]
+ - Never writes to: Section 1, Section 6
+ ````
+
+ This prevents skills from silently overwriting sections they shouldn't touch.
+
+ ---
+
+ ## 10. Version Increment Rules
+
+ | Change type | Increment |
+ |---|---|
+ | Typo, wording fix, minor clarification | PATCH (1.0.0 → 1.0.1) |
+ | New section, new check, new operating rule, new step | MINOR (1.0.0 → 1.1.0) |
+ | Restructured logic, changed intake, new output format, new section order | MAJOR (1.0.0 → 2.0.0) |
+ | Patched from a live session finding | PATCH with session note in changelog |
+
+ Always update `last_updated` on every change regardless of increment size.
+
+ ---
+
+ ## 11. Eval Format
+
+ Every skill needs `evals/skill-name.eval.md`. Minimum 3 test cases.
+
+ ````markdown
+ ## Test Case N: Descriptive name
+
+ **Input:**
+ [Realistic user prompt or scenario]
+
+ **Expected output includes:**
+ - [Specific element that must be present]
+ - [Specific element that must be present]
+
+ **Expected output excludes:**
+ - [What should NOT appear]
+
+ **Pass condition:**
+ [Single sentence defining what "correct" looks like]
+ ````
+
+ One test case must be an **edge case** (missing context, ambiguous input, conflicting signals).
+ One test case must test the **quality gate** specifically.
+
+ **No `## Changelog` section in an eval file** — same rule as `SKILL.md`
+ (Section 5). An eval file that invents a version history is fabricating
+ a release record, not documenting one.
+
+ **Test the skill's real output shape, not an aspirational one.** A
+ Session Logging or Learning Close eval must assert against the exact
+ YAML fields the skill's own `SKILL.md` actually writes — for a T1/T2
+ skill (or a T3 skill that has chosen to add one), that's the four-field
+ Learning Close row from Section 5.1 (`skill`, `session_date`, `pattern`,
+ `source`), nothing richer. An eval that tests fields the skill doesn't
+ produce (invented scores, counts, or metadata) will pass or fail
+ independent of what the skill actually does — it stops being a test.
+ If a skill has no session-logging mechanism at all, its eval suite
+ should not contain a Session Logging test case; write a short note
+ instead of a fabricated one. **Found and fixed across 6 eval files on
+ 2026-08-24** — see `CHANGELOG.md` for the full list.
+
+ ---
+
+ ## 12. Skill Tiers
+
+ | Tier | Description | Examples | Requirements |
+ |---|---|---|---|
+ | **T1 — Strategic** | High-stakes, executive or customer-facing output | pre-mortem, positioning-messaging, go-to-market-strategy | All 7 sections + operating rules + quality gate + Learning Close |
+ | **T2 — Execution** | Day-to-day PMM work, high frequency, medium stakes | experiment-doc, prd, retro, stakeholder-maps, gaccs-brief, pmm-okrs, beachhead-segment | All 7 sections + quality gate + Learning Close |
+ | **T3 — Utility** | Tactical outputs, lower stakes | writing-assistant, pmm-resume, privacy-policy, interview-summary, prioritization-frameworks | All 7 sections. Quality gate optional. Learning Close optional. |
+ | **T4 — Meta** | Skills that operate on other skills | meta-review, meta-learn, meta-verify, meta-synthesis, workflow-orchestrator, product-marketing-context | Custom per meta skill. All 7 sections still required. |
+
+ **Note on this table (2026-08-22):** `competitive-battlecard` and
+ `buyer-personas` were removed from the T1/T2 examples above — both were
+ named here as if they were live skills, but neither exists in this repo.
+ `beachhead-segment` was added to T2 — it was previously missing from this
+ table entirely despite being a fully built, brain-writing skill that meets
+ every T1/T2 structural requirement. If either phantom skill is built later,
+ re-add it here at that time; until then, naming it here was a standing
+ inaccuracy this table shouldn't carry forward.
+
+ **Note on enforcement (2026-08-24):** This table's "All 7 sections still
+ required" language for every tier, including T3 and T4, was accurate but
+ unenforced — 11 of 21 skills were missing one or more of the seven required
+ sections, had non-canonical header casing or numbering, or had `version`
+ and `metadata` fields misplaced or absent entirely. All 21 skills in this
+ repo now pass a full-section audit against this table. See each skill's
+ own `last_updated` date for when its fix landed.
+
+ **Note on prioritization-frameworks (2026-08-24):** This T3 skill's eval
+ suite tested a Learning Close mechanism the skill didn't actually have —
+ a mismatch found while auditing eval files for fabricated content (see
+ Section 11). Rather than delete the eval to match the skill, the skill was
+ given a real Learning Close (Step 7, T3's optional case exercised
+ deliberately) so the eval could test something true. This is the one skill
+ in T3 that now writes to `/context/skill-sessions.md`; every other T3
+ skill remains log-free by design.
+
+ ---
+
+ ## 13. The `review` Meta Skill Checklist
+
+ When the `review` meta skill audits a `SKILL.md`, it checks these in order. Use this list for self-review before committing.
+
+ **Frontmatter (5 checks):**
+ - [ ] All required fields present
- [ ] `name` matches directory name exactly
- - [ ] `description` is 1-1024 chars with trigger phrases
- - [ ] `SKILL.md` is under 500 lines
- - [ ] Brain-dependent skills correctly cite real brain sections (see
- `SKILL-SPEC.md` Section 8-9)
- - [ ] No sensitive data or credentials
- - [ ] Examples match actual skill behavior — don't reference a skill,
- command, or file that doesn't exist in this repo
+ - [ ] `description` is 300–600 chars and includes trigger phrases verbatim
+ - [ ] `metadata.context` declared as `brain-dependent` or `context-agnostic`
+ - [ ] `version` and `last_updated` present
- ## Versioning
+ **Seven required sections (7 checks):**
+ - [ ] `## Trigger` — includes When, Not for, Example prompts
+ - [ ] `## Inputs` — all three sub-fields present (or `n.v.t.`)
+ - [ ] `## Pre-flight` — present (or explicit `n.v.t.`)
+ - [ ] `## Steps` — named steps in imperative form, at least 2 steps
+ - [ ] `## Outputs` — all three sub-fields present (or `n.v.t.`)
+ - [ ] `## Verification` — concrete and checkable (or explicit `n.v.t.`)
+ - [ ] `## Do Not Use For` — present with routing (or explicit `n.v.t.`)
- This repo uses one version number across the entire repo, not independent
- per-plugin versions. `marketplace.json`, every `plugin.json`, and the
- newest `CHANGELOG.md` heading always carry the same version. See
- `CLAUDE.md` for the full rule and release procedure.
+ **Tier-appropriate sections (3 checks):**
+ - [ ] `## Operating Rules` present with ≥6 rules (T1/T2)
+ - [ ] `## Quality Gate` present with ≥5 binary checks (T1/T2 where `quality_gate: true`)
+ - [ ] `## Steps` ends with a Learning Close step, per Section 5.1 (T1/T2)
- ## Cross-Skill References
+ **Quality (3 checks):**
+ - [ ] `SKILL.md` is ≤500 lines
+ - [ ] Output template is in a code fence (not raw markdown headers)
+ - [ ] Evals file exists with ≥3 test cases including one edge case
- When adding new skills, only reference other skills by name if they
- actually exist in this repo — verify the folder and frontmatter `name:`
- field before citing a skill in your own `description` or routing text.
+ **Pass threshold:** 16/18 checks. Skills below this are flagged for improvement before next use.
+
+ **Not checked (by design):** `## Changelog` is not part of this checklist.
+ See Section 5 — it is not required under this version of the spec.
+
+ ---
+
+ ## 14. What Makes a Skill "Best in Class"
+
+ A best-in-class skill has five properties:
+
+ **1. It fails gracefully.** Missing context, vague input, and interrupted sessions are handled explicitly — not silently producing generic output.
+
+ **2. It enforces its own quality.** The quality gate runs before output is delivered. A skill that can produce a bad output without flagging it is not production-grade.
+
+ **3. It knows its boundaries.** The `## Do Not Use For` section names where the skill ends and routes clearly to what comes next. Users never wonder whether they're in the right skill.
+
+ **4. It compounds through the shared system, not its own private loop.** No individual skill runs its own self-improvement pipeline. T1/T2 skills log each session to `/context/skill-sessions.md` via the standard Learning Close step (Section 5.1); `meta-synthesis` is where patterns get detected across sessions and skills, and any resulting guardrail or brain update goes live for every skill to read at Pre-flight. A skill gets smarter over time by being part of that shared system — not by inventing its own memory.
+
+ **5. It hands off cleanly.** The `## Trigger` section names specific routing conditions — not vague "you could also run X." The handoff is precise enough that the user never wonders what to do next.
+
+ ---
+
+ ## 15. SKILL.md Template
+
+ Copy this to `skills/<skill-name>/SKILL.md` when creating a new skill. Fill every section. Use `n.v.t.` where genuinely not applicable — never leave a section blank or omit it.
+
+ ````markdown
+ ---
+ name: skill-name
+ version: 1.0.0
+ description: >
+ What this skill does + 3–5 trigger phrases verbatim. 300–600 chars.
+ Trigger phrases here drive auto-fire. Explanatory prose goes in the body.
+ metadata:
+ author: Stefanos Karakasis
+ context: brain-dependent
+ quality_gate: true
+ last_updated: YYYY-MM-DD
+ ---
+
+ # Skill Name
+
+ One paragraph. What this skill does and why it exists. No commands, no
+ section headers — just the essence. Someone reading this should know
+ immediately whether this is the right skill.
+
+ ## Trigger
+
+ - **When:** [Condition. One sentence.]
+ - **Not for:** [Explicit exclusions with routing to correct skill.]
+ - **Example prompts:**
+ - "[exact phrase 1]"
+ - "[exact phrase 2]"
+ - "[edge case that should also work]"
+
+ ## Inputs
+
+ - **Args:** [n.v.t. if none]
+ - **Defaults:** [n.v.t. if no defaults]
+ - **Context keys:** [Files, brain sections, external resources needed.
+ n.v.t. if context-agnostic.]
+ - **Brain contract:** Reads: [sections]. Writes: [sections]. Never writes to: [sections].
+
+ ## Pre-flight
+
+ - [Dependency check or early-exit condition]
+ - n.v.t.
+
+ ## Steps
+
+ ### Step 1: [Name — imperative]
+
+ [Action. Concrete.]
+
+ ### Step 2: [Name]
+
+ [Next action.]
+
+ ### Step N: Learning Close
+
+ [T1/T2 only — copy the template block from Section 5.1 verbatim, renumbered.
+ Omit this step for T3/T4 skills unless the author opts in.]
+
+ ## Outputs
+
+ - **Files written:** [path → what's in it. n.v.t. if read-only. T1/T2 skills
+ also list `/context/skill-sessions.md` — one row per session.]
+ - **Chat output format:** [markdown shape. n.v.t. if no chat output.]
+ - **External side effects:** [n.v.t. if none.]
+
+ ## Verification
+
+ - [How to confirm the skill ran correctly. Concrete.]
+ - n.v.t.
+
+ ## Do Not Use For
+
+ - **[skill-name]** — [When to use that skill instead.]
+ - n.v.t.
+
+ ---
+
+ ## Operating Rules
+
+ - **Rule.** Reason.
+
+ ## Quality Gate
+
+ | Check | Standard | Pass = |
+ |---|---|---|
+ | [Check] | [What it tests] | [Pass condition] |
+ | Learning Close ran | `/context/skill-sessions.md` has a new row for this session | Yes |
+ ````
+
+ No `## Changelog` section — not required under this version of the spec.
+ See Section 5.
+
+ ---
+
+ *This spec is a living document. When patterns emerge across multiple skills that should be standardised, update the spec and increment its version. The spec version tracks separately from individual skill versions.*