Skdd Harvest

SkDD Harvest — Knowledge Harvesting from Daily Work

Purpose

Quickly harvest knowledge born from daily LLM collaboration into reusable Skills. If skill-creator is a "workshop for designing and evaluating polished skills", skdd-harvest is "picking ripe knowledge from today's fieldwork". When skill-creator (or a successor) is present in a session, skdd-harvest still owns the harvest decision — what to harvest, when, and under which threshold — and defers only format mechanics to it (see "Authoring Conventions").

The unit of value is How with its Why attached. A bare How (procedure without the judgment behind it) is brittle: when the context shifts, no one can tell whether the procedure still applies. Keep the living Why inline in each skill so future agents can adapt instead of blindly following.

Project Configuration

• Project skill prefix: {{SKDD_PREFIX}} (naming: {{SKDD_PREFIX}}<domain>-<action>)
• Project skills live under .claude/skills/
• Proto-Skill backlog: .claude/skills/skdd-harvest/backlog.md (per-developer local state, gitignored)
• Harvest threshold: {{SKDD_THRESHOLD}} — see "Harvest Threshold" below

Invocation

Explicit triggers

• User says "skillify this", "harvest", "/harvest", "turn this into a skill"
• User points at a specific procedure and says "I want to keep this"

Autonomous triggers (governed by the SkDD section in AGENTS.md)

• The agent detects a skill candidate at a natural task completion point AND the candidacy criteria threshold ({{SKDD_SCORE_MIN}}/5 or more) is met
• A Proto-Skill has appeared in {{SKDD_PROMOTE_SESSIONS}}+ separate sessions and qualifies for promotion

When NOT to propose

• The candidacy threshold is not met (fewer than {{SKDD_SCORE_MIN}}/5 criteria)
• The session consisted only of simple Q&A with no procedural knowledge
• The knowledge is already covered by an existing skill (propose an update instead)

Candidacy Criteria (the 5 criteria)

1. Recurrence — the situation is likely to come up again
2. Proceduralness — there is a repeatable sequence of steps
3. Non-obviousness — the knowledge is not derivable from docs or common sense
4. Correction-derived — it came from a user correction or a trial-and-error fix
5. Generality — it applies beyond the single file/ticket at hand

Score each criterion as met/not met. Where the bar sits is set by the harvest threshold below: {{SKDD_SCORE_MIN}}/5+ → propose. {{SKDD_PROTO_BAND}}/5 → Proto-Skill. Below that → nothing.

Harvest Threshold

Active level for this project: {{SKDD_THRESHOLD}}. Apply that block below and ignore the others. The level is chosen at install time and changed with /skdd:config — it is not a judgment call to make per session.

Why a dial at all: the right harvest rate is not universal. A fresh project with no skills needs eager capture; a mature one needs the opposite — every new skill dilutes the set and makes the right one harder to find. Raising the level tightens three things at once: the score bar, the bias toward updating an existing skill rather than adding one, and how hard the writing must be distilled.

low — harvest eagerly (bootstrapping a new or under-documented project)

• Propose at 2/5+; Proto-Skill at 1/5; nothing at 0/5
• Promote a Proto-Skill after 2 separate sessions
• Consolidation: create a new skill unless an existing one clearly already covers it
• Distillation: SKILL.md under 500 lines

medium — the balanced default

• Propose at 3/5+; Proto-Skill at 1-2/5; nothing at 0/5
• Promote a Proto-Skill after 2 separate sessions
• Consolidation: when the knowledge overlaps an existing skill's scope, propose an update to that skill instead of a new one
• Distillation: SKILL.md under 500 lines; one skill = one <domain>-<action>

high — keep the skill set small and sharp

• Propose at 4/5+; Proto-Skill at 2-3/5; nothing at 0-1/5
• Promote a Proto-Skill after 3 separate sessions
• Consolidation: BEFORE proposing anything new, list .claude/skills/ and read every existing SKILL.md frontmatter description. If ANY of them overlaps, the answer is an update, not a new skill.
• Distillation: SKILL.md under 200 lines; one skill = one decision axis. Transcribing the steps you just performed is not harvesting — state the rule that would let a future agent derive those steps.

max — only knowledge that changes how future work is judged

• Propose at 5/5; Proto-Skill at 3-4/5; nothing at 0-2/5
• Promote a Proto-Skill after 4 separate sessions
• Consolidation: never create a new skill while any existing skill could host the knowledge. A new skill requires an explicit statement of the gap no existing skill fills.
• Distillation: SKILL.md under 120 lines; Why and decision rules only. Reproducible procedures belong in references/; the judgment stays in SKILL.md.

Authoring Conventions — two layers

A harvested skill mixes two kinds of rules. Keep them separate:

Layer 1 — SkDD invariants. Defined by this file and its references; no external guidance overrides them: the 5 candidacy criteria; the harvest threshold with its per-level bars and length caps; the SKILL.md + harvest.md pair and the atomic-update transaction; naming ({{SKDD_PREFIX}}<domain>-<action>) and project/global routing; the oscillation guard; never renaming a skill.

Layer 2 — platform authoring conventions. The SKILL.md frontmatter field set, description/trigger phrasing style, body section skeleton, progressive-disclosure norms (when and how to split into references/), and skill directory location phrasing. These evolve with the platform faster than this plugin ships, so resolve them fresh every time you generate or update a skill:

1. If a dedicated skill-authoring skill is available in this session (e.g. Anthropic's skill-creator), follow its current guidance for these format/structure mechanics.
2. Otherwise, apply your own current knowledge of the platform's Skills authoring best practices.
3. If neither yields guidance you are confident is newer, use the dated baseline in Step 3 as written.

Precedence: SkDD invariants > newer platform guidance (1-2) > dated baseline. When uncertain whether guidance is genuinely newer than the baseline, prefer the baseline — a misremembered "new convention" is worse than a dated real one. Do not fetch documentation to resolve this; the chain must work offline in every harvest.

Workflow

Step 1: Knowledge Extraction

Analyze the current conversation and identify knowledge worth skillifying.

Extraction priority (highest first):

1. Points the user corrected or flagged — the richest source of tacit knowledge
2. Final procedures reached after trial and error
3. Domain knowledge the user explicitly taught
4. Constraints, prerequisites, and pitfalls discovered during work

Types of knowledge to extract:

• Procedures (what to do and in what order)
• Decision rules (when to branch and how)
• Prohibitions (what breaks things, anti-patterns to avoid)
• Tool-specific know-how (practical wisdom not in the docs)
• Domain terminology (team-internal meanings and definitions)

Step 2: Routing and Skill Design (agreement with user)

Scope overlap check (run this before designing anything new):

List .claude/skills/ and read each existing SKILL.md's frontmatter description. If the knowledge falls inside an existing skill's scope, stop here and go to "Updating Existing Skills" — do not design a new skill. How much overlap is disqualifying is set by the active threshold level's Consolidation rule.

A name-collision check is not an overlap check: two skills can have entirely different names and still cover the same ground, which is the usual way a skill set rots.

Route the knowledge first:

• Project-specific (depends on this repository's conventions, systems, or domain) → project skill named {{SKDD_PREFIX}}<domain>-<action> under .claude/skills/
• Generic (would hold in any project) → suggest a global skill under ~/.claude/skills/<domain>-<action> instead (no project prefix)

Present the following concisely and get approval:

📦 Skill Proposal
─────────────────────
Name:     <name with or without prefix per routing>
Location: project (.claude/skills/) | global (~/.claude/skills/)
Summary:  <one-line description>
Scope:    <2-3 bullet points>
Trigger:  <"when you want to...", "when asked to...">
Criteria met: <which of the 5 criteria apply>
Threshold: {{SKDD_THRESHOLD}} (bar: {{SKDD_SCORE_MIN}}/5)
Overlap:  <which existing skills were considered, and why none can host this>
─────────────────────
Shall I generate this?

Naming convention:

• {{SKDD_PREFIX}}<domain>-<action> for project skills (e.g., {{SKDD_PREFIX}}repository-test)
• Verify no name collision with existing skills (list .claude/skills/ first)

If context is already clear (e.g., user said "skillify this" mid-conversation), minimize confirmation and move quickly to generation.

Step 3: Generate the SKILL.md + harvest.md pair

Every harvested skill is a pair:

• SKILL.md — the current snapshot of Why + How
• harvest.md — the append-only decision record (ADR) of how the skill evolved

Before writing, resolve the Layer-2 format mechanics via the chain in "Authoring Conventions". The subsections below tagged [baseline — as of 2026-08] are the fallback snapshot: apply them as written when the chain yields nothing newer; let newer platform guidance supersede them. Untagged subsections are SkDD invariants.

Directory structure [baseline — as of 2026-08]

skill-name/
├── SKILL.md              (required — current Why+How snapshot)
├── harvest.md            (required — append-only ADR; see references/adr-entry-schema.md)
└── references/            (only if supplementary content exceeds 300 lines)
    └── <topic>.md

The SKILL.md + harvest.md pairing is a SkDD invariant; the references/ split rule (including the 300-line trigger) is Layer 2 — follow the platform's current progressive-disclosure norm if newer.

SKILL.md structure template [baseline — as of 2026-08]

Frontmatter field set, description style, and body skeleton are Layer 2 — the chain may supersede any of them. That the skill exists as this pair, under the active length cap, with its Why inline, is Layer 1.

---
name: <skill-name>
description: >
  <What this skill does and when to use it.
   Be specific about triggers. Include related keywords for triggering accuracy.
   Write slightly pushy to ensure the skill fires when relevant.>
---

# <Skill Title>

## Overview

<The problem this skill solves. 2-3 lines.>

## Prerequisites

<Required tools, environment, or knowledge. Omit if none.>

## Procedure

<Step-by-step instructions. Write in imperative form.>
<Attach "why" to each step: "because...", "otherwise X will happen".>

## Decision Rules

<Branching logic and conditions. Omit if none.>

## Pitfalls & Warnings

<Things that break, anti-patterns, gotchas.>
<Concentrate insights from user corrections here.>

## Examples

<Input/Output examples if available.>

harvest.md initial entry

Create harvest.md with entry 001 following references/adr-entry-schema.md: context = what situation produced this skill, change = the initial Why + How in one or two lines, supersedes = —.

Writing principles

Always (SkDD invariants):

• Attach why: "because...", "otherwise X happens", "this prevents..." — a How without its Why is not a harvest
• Respect the length cap of the active threshold level (see "Harvest Threshold"). If longer, move supplementary content out of SKILL.md following the current progressive-disclosure convention (baseline: references/ with pointers from SKILL.md)

Baseline style [as of 2026-08 — the chain may supersede]:

• Imperative form: "Run...", "Verify...", "Do not..."
• Define domain terms on first use with a brief parenthetical
• Description is comprehensive: include multiple phrasings a user might say to maximize trigger accuracy

Step 4: Output

1. Write the skill directory (SKILL.md + harvest.md) to .claude/skills/<name>/ for project skills, or ~/.claude/skills/<name>/ for global skills
2. Suggest git add for project skills (skills are committed; backlog.md is not)

Proto-Skill (Seed Planting)

Record knowledge that does not yet meet the skillification threshold but may recur.

Recording condition

• The score lands in the Proto-Skill band for the active threshold level ({{SKDD_PROTO_BAND}}/5) — below the proposal bar of {{SKDD_SCORE_MIN}}/5
• The knowledge feels like "might be a one-off, but worth tracking"

Recording format — append to .claude/skills/skdd-harvest/backlog.md

## <topic>

- **Criteria met**: <which criteria> (n/5)
- **Sessions**: <count>
- **Summary**: <one line, with key insights as sub-bullets>
- **Date**: <YYYY-MM-DD>
- **Note**: <promotion condition, user responses, related skills>

Promotion condition

When a Proto-Skill appears in {{SKDD_PROMOTE_SESSIONS}} or more separate sessions, propose skillification: "The knowledge about that I noted earlier came up again in this session. It might be time to turn it into a proper skill. Shall I?"

Updating Existing Skills

When new insights fall within an existing skill's scope:

1. Propose an update, not a new skill
2. Show the diff explicitly: "I suggest adding X to the 'Pitfalls' section of skill Y"
3. Classify the change:
   • Decision-level (approach change, new constraint, rejection of an alternative, threshold change) → perform the atomic update: draft the harvest.md entry FIRST, then apply the SKILL.md edit and append the entry in the same transaction. See references/harvest-protocol.md.
   • Trivial (typo, wording, an example that changes no guidance) → edit SKILL.md directly; no harvest.md entry.
4. Check the oscillation guard: before re-adopting an approach, scan harvest.md for an entry that already rejected it (see harvest-protocol.md)
5. Preserve the original skill name and directory name — do not rename
6. Modernize only what you touch: apply the current Layer-2 conventions (see "Authoring Conventions") to the sections being edited, but never rewrite or restyle a whole skill just to match newer format conventions — that is churn, not growth. A style-only modernization of a touched section is a trivial edit (no harvest.md entry).