Skip to content

Skills under-demonstrate and under-name their core concepts #181

Description

@philippe-ths

What needs to change

Two related authoring gaps surfaced across the skill set. Both are judgment-heavy and per-skill, not a mechanical sweep; this issue tracks the class.

  1. Demonstrate, don't describe. Several skills are entirely abstract where a single worked example of the hard case would retire multiple rules. Candidates: a filled plan skeleton (aiw-planning), a semantically-wrong-but-green output (aiw-verification), a drifted context line vs its correction (aiw-project-context-management), a baseline-anchored benchmark (aiw-performance-profiling), a filled contradiction block (aiw-failure-analysis), a concrete modality-conflict pair (aiw-ground-truth).
  2. Leading words. Each of these skills turns on a governing concept that is never coined and reused at the step that depends on it. Candidates: "coverage" (aiw-verification), "trust collapse" reused at the audit (aiw-failure-analysis), "drift" (aiw-project-context-management), "baseline" (aiw-performance-profiling).

Each skill is its own decision.

Why / what triggered it

Surfaced by running aiw-prompt-smith across the skill set. An adjective leaves room the model fills with its average; one good example, and a named concept reused at the key step, steer better than more prose.

Affected files (each mirrored in .agents/skills/)

  • .claude/skills/aiw-planning/SKILL.md
  • .claude/skills/aiw-verification/SKILL.md
  • .claude/skills/aiw-failure-analysis/SKILL.md
  • .claude/skills/aiw-ground-truth/SKILL.md
  • .claude/skills/aiw-performance-profiling/SKILL.md
  • .claude/skills/aiw-project-context-management/SKILL.md

Acceptance criteria

  • Where an example is added, it demonstrates the hard case and lets abstract rules shrink; net length should not grow materially (hold to the elegance check).
  • Where a leading word is introduced, it is reused at the key step, not on every line.
  • Changes stay behaviour-preserving; both skill directories identical; version bump with CHANGELOG entry; lite parity preserved.

Skills that may help

  • aiw-prompt-smith

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions