# Three-bucket classification

When porting a skill, every piece of the source maps to one of three buckets. Surface this classification to the user **before** writing the adapted skill — never silently rewrite.

## Bucket 1: Keep verbatim

What it is: format, schema, mechanic, scripts, frameworks, regex patterns, JSON shapes, math/algorithm details.

Why: this is the *value* the source is bringing. Reinventing wastes effort and risks bugs.

Examples:
- The 38 decision questions from the 37signals decision skill
- ffmpeg flag patterns for frame extraction
- A regex for detecting URLs in a post
- A JSON schema for the output payload
- Specific API endpoints + auth patterns
- The viewport-base.css from frontend-slides
- The Karpathy LLM wiki schema rules

Action: **copy as-is**. Optionally add a `<!-- from <source> -->` marker.

## Bucket 2: Adapt

What it is: tool defaults, paths, voice, naming, opinions, user-context examples.

Why: these are the source author's preferences. Yours differ.

### Sub-buckets to look for

| Sub-bucket | Source has | Adapt to |
|---|---|---|
| **Naming** | Their convention | Verb-noun (matches `watch-video`, `read-book`, `create-skill`) when possible |
| **Tool defaults** | Their video tool | Your `watch-video` |
| | Their kanban | Your `pm` |
| | Their transcript tool | Your `watch-video transcript` mode |
| | Their notes / KB | Your `second-brain` (or `${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/`) |
| | Their decision framework | Your `decide` |
| | Their social drafting | Your `jab-hook` |
| | Their research | Your `deep-research` |
| **Paths** | `~/outputs/` or `~/notes/` | `~/Documents/<skill>-<...>` convention |
| | Custom config dirs | Your `references/` pattern |
| **Voice** | Generic / corporate / theirs | Yours — direct, conviction-coded, listener-perspective, no AI-slop |
| **Context** | "The user," generic examples | Your specific context (your name, your products / portfolio / partnerships) where the skill needs it |
| **Defaults** | Their assumed environment | Your Mac, MLX-Whisper, brew, uv, Notion API key, Typefully MCP, etc. |
| **Cadence** | Their suggested frequency / WIP limits | Yours (e.g., 2 promo/week for social, 3 In-Progress WIP for pm) |

Action: **rewrite** the affected lines, surface the change in the bucket report.

## Bucket 3: Add

What it is: cross-references, composition notes, your conventions that the source doesn't know about.

Why: the source is generic; your version sits in a network of other skills.

Examples:
- "Composes with `decide`" (when the skill hits a decision moment)
- "Outputs to `second-brain raw/` as `<prefix>-`"
- "Falls back to `social-fetch` for the URL fetch step"
- "Uses MLX-Whisper local (see install in `watch-video` references)"
- Memory references: `feedback_*` files in `~/.claude/memory/`
- BACKLOG.md entry if the adapt spawns sub-ideas

Action: **add net-new sections** to the adapted SKILL.md — typically a `## Composes with` section and inline references in the body.

## Bucket report format

Present to the user before writing:

```markdown
## Three-bucket classification — <source skill name>

### Keep verbatim
- <piece 1>
- <piece 2>

### Adapt
- <source piece> → <new version> (why: <reason>)
- <source piece> → <new version> (why: <reason>)

### Add
- <new piece> (compose with `<your skill>`)
- <new piece>

**Proceed?** y/n / edit
```

the user approves, edits, or rejects. Only then proceed to write the adapted SKILL.md.

# License check

Run this before adapting. Skill defaults to **stop** on unclear or restrictive licenses — don't proceed without explicit the user approval on red cases.

## Policy

| License | Action | Why |
|---|---|---|
| **MIT** | ✅ Proceed | Permissive. Requires only attribution + license notice. |
| **Apache 2.0** | ✅ Proceed | Permissive. Requires attribution + NOTICE file. |
| **BSD (2-clause, 3-clause)** | ✅ Proceed | Permissive. Requires attribution. |
| **ISC** | ✅ Proceed | Equivalent to MIT. |
| **CC0 / Public Domain** | ✅ Proceed | No attribution required (but include anyway for credit). |
| **Unlicense** | ✅ Proceed | Public domain equivalent. |
| **MPL 2.0** | 🟡 Warn | File-level reciprocity — modified MPL files must stay MPL. Adapt sparingly; consider rewriting from scratch instead of copying. |
| **LGPL** | 🟡 Warn | Library-linking exception, but skill files would be derivative. Usually rewrite from scratch is cleaner. |
| **GPL 2.0 / 3.0** | ❌ Stop | Strong copyleft — adaptation creates a derivative work that must also be GPL. Stops your repo from being your-license-of-choice. Surface to the user. |
| **AGPL** | ❌ Stop | Even stronger — network-use clause triggers. |
| **Custom / proprietary** | ❌ Stop | No legal basis to copy. |
| **No LICENSE file** | 🟡 Warn | Default copyright = no rights. Don't copy. Ask author OR rewrite from scratch using only the *ideas* (not the text). |
| **Unclear / conflicting** | 🟡 Warn | Surface to the user for a call. |

## Detection script

```bash
# In the source repo
curl -s "https://api.github.com/repos/<owner>/<repo>/license" | jq -r .license.spdx_id
```

Or read the LICENSE file directly:

```bash
cat <repo>/LICENSE | head -5
```

Standard SPDX identifiers: `MIT`, `Apache-2.0`, `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `MPL-2.0`, `LGPL-3.0`, `GPL-2.0`, `GPL-3.0`, `AGPL-3.0`, `CC0-1.0`, `Unlicense`.

## Required artifacts per license

**MIT / BSD / ISC**: copy the LICENSE text into `references/attribution.md` (or as a separate `LICENSE-<source-name>` file in the skill dir). Include the copyright line verbatim.

**Apache 2.0**: same as MIT + copy any `NOTICE` file from the source.

**CC0 / Unlicense / Public Domain**: attribution not required, but include in `attribution.md` for credit.

**MPL / LGPL / GPL**: don't proceed without the user's explicit call.

## When the source has no license

This is the most common case for skills on personal GitHub repos. Treat it as ❌ red:
- Default copyright applies — you have *no* right to copy or redistribute
- Options:
  1. **Open an issue / PR** asking the author to add a permissive license
  2. **Email / DM** the author and ask permission, save the response
  3. **Rewrite from scratch** using only the *ideas* (mechanics, concepts) — not the text. Then it's a fresh independent work that happens to be similar. Document this clearly in `attribution.md` so it's not confused with a port.

## Edge case: skills you wrote yourself in another context

If the source is YOUR OWN code in another repo of yours (e.g., personal note → adapt for a sibling plugin), license doesn't apply. Skip this step and just attribute for traceability.

# Change types — what to look for

Taxonomy of update-worthy signals. When in `from-chat` or `from-dump` mode, scan for these.

## 1. Corrections

User explicitly said the current behavior is wrong.

**Signals:**
- "no don't do that"
- "stop doing X"
- "this isn't right — should be Y"
- "we got this wrong before"
- Direct feedback after a skill ran

**Examples from this session:**
- "i dont always want to link somewhere" → updated jab-hook's link placement rule
- "for the slide deck skill, we need to really emphasize for the voice and tone to be super conversational since its something that will literally be spoken out" → updated slide-deck voice rules

**Version bump**: PATCH if clarification, MINOR if a real behavior change.

## 2. Validations

User confirmed a behavior worked well — bake it in so it doesn't regress.

**Signals:**
- "yes that worked"
- "perfect, do that again"
- "this approach was right"
- Accepted a draft without changes

**Action**: lock in the choice as explicit rule (don't leave it as ad-hoc judgment).

**Version bump**: PATCH.

## 3. New patterns

the user used a workflow not documented in any skill. Encode it.

**Signals:**
- A multi-step process performed manually
- A tool combination that worked
- A specific decision-making chain

**Action**: either:
- Add the pattern to an existing skill if it fits
- Spin off as a new skill via `create-skill`

**Version bump**: MINOR (it's a new capability for the skill).

## 4. Voice / tone updates

Refinements to how the skill writes / sounds.

**Signals:**
- Style feedback
- "Make it more X" / "less Y"
- Examples where the user rewrote the skill's output

**Examples from this session:**
- Spoken-aloud rule for slide-deck — overhauled the voice section
- Conversational rules (contractions, "you" not "the audience," numbers said naturally)

**Action**: edit the relevant `voice.md` / `narrative-and-voice.md` / equivalent reference.

**Version bump**: PATCH for tweaks; MINOR if a major voice principle changes.

## 5. Tool changes

the user switched default tools or learned a tool integration works better.

**Signals:**
- "Use X instead of Y"
- "Set up Z" (during setup conversation)
- "MLX-Whisper works on Mac"

**Examples from this session:**
- Installed `uv` + MLX-Whisper → `watch-video` references this in transcript backend selection
- ScrapeCreators / Apify keys → `social-fetch` paid-fallback strategies

**Action**: update the relevant references/adapters file. Propagate to other skills using the same tool.

**Version bump**: PATCH if just preferences; MINOR if it changes the default behavior.

## 6. Architectural decisions

Decisions about how skills themselves are structured.

**Signals:**
- Naming convention changes (verb-noun vs noun-verb)
- File layout conventions (references/, templates/)
- Frontmatter format
- Cross-reference patterns

**Examples from this session:**
- Rename `video-watch` → `watch-video` for verb-noun consistency
- Rename `my-social` → `jab-hook` for framework citation
- "Don't add comments unless logic is non-obvious"

**Action**: usually cross-cuts — apply to multiple skills + save the principle to memory.

**Version bump**: MAJOR if it's a breaking rename; MINOR otherwise.

## 7. Gaps

Something the skill should have handled but didn't.

**Signals:**
- A skill ran and missed an obvious case
- "Why didn't it do X?"
- An edge case surfaces in a real run

**Action**: add the case to the skill's body — usually a new section, table row, or error-handling entry.

**Version bump**: MINOR (capability added).

---

## How to phrase a learning

Each learning extracted from chat / dump should be a **single change** stated as:

> *"[skill or area] should [new behavior] because [reason]. Currently does [old behavior]."*

Examples:
- *"slide-deck voice should emphasize that slides are spoken aloud (write for the ear) because the current 'written voice' framing produced text that didn't sound natural when read out loud."*
- *"jab-hook drafts should not include URLs in the post body (use first comments instead) because platforms downrank link-in-body posts."*
- *"second-brain raw/ type catalog should include business-operational prefixes (call-, email-, sop-, etc.) because the user uses these for agency work, not just personal intellectual capture."*

Format: skill (or area) + new behavior + because + (optional) current behavior contrast.

If you can't phrase it this way, it's not concrete enough to be a change — push back / ask the user for specifics.

# Cross-skill propagation

The unique value of `update-skill`. A learning often applies to multiple skills — surface all of them so the user can approve per file.

## Why this matters

Examples from this session where a single learning crossed skills:

| Learning | Affected skills |
|---|---|
| Link placement rule (no URLs in body) | `jab-hook` + memory `feedback_social_link_placement.md` (applies to any other social skills in your sibling repos too) |
| Verb-noun naming convention | `watch-video`, `read-book`, `create-skill`, `adapt-skill`, `update-skill` (rename pass across multiple skills) |
| Anti-AI-slop banned phrases | `slide-deck`, `jab-hook` (both write content; both should ban "dive deep," "leverage," etc.) |
| Spoken-aloud voice rule | `slide-deck` (load-bearing); `jab-hook` partial relevance (social IS read silently usually, but voice still applies) |

Without propagation, these rules drift — one skill knows about it, others don't. Subtle inconsistency creeps in.

## Discovery: how to find affected skills

For each learning, do three passes:

### Pass 1: Keyword search

Grep for terms that signal the topic. Cast a wide net.

```bash
# Example: link placement learning
grep -rln "URL\|link\|outbound\|first comment" ~/code/makerskills/skills/ --include="*.md"

# Across all sibling repos (list yours in $MAKERSKILLS_CONFIG/skillify/repos.yaml):
config="${MAKERSKILLS_CONFIG:-$HOME/.config/makerskills}/skillify/repos.yaml"
for raw in $(yq -r '.repos[].path' "$config" 2>/dev/null); do
  repo="${raw/#\~/$HOME}"  # expand leading ~ to $HOME
  if [ -d "$repo/skills/" ]; then
    grep -rln "URL\|link\|outbound\|first comment" "$repo/skills/" --include="*.md" 2>/dev/null
  fi
done
```

### Pass 2: Semantic match (manual)

For each grep hit, read the matching section and ask: *is this rule actually applicable here, or is the keyword match coincidental?*

- **Direct match** — same topic + same activity (e.g., link rule in a social drafting skill): high confidence
- **Adjacent match** — same topic, different activity (link rule mentioned in a research skill that cites URLs): medium confidence
- **Coincidental match** — keyword present but unrelated context: skip

### Pass 3: Adjacent-skill scan (no grep)

Some learnings won't have keyword matches but logically apply. Manually scan the list of all skills and ask: *does this rule apply here even if the keyword isn't present?*

Example: a "voice should be spoken aloud" rule won't grep-match in `pm` (project management skill — no voice content), but it applies in any skill that produces user-facing text (`slide-deck`, `jab-hook`, `read-book` summaries, `create-skill` output).

Use the skill's *output type* as the heuristic:
- **Writes user-facing text** (drafts posts, slides, summaries): voice rules apply
- **Generates structured data** (boards, archives, schemas): voice rules usually don't apply
- **Wraps an external tool** (yt-dlp, ffmpeg, Playwright): tool rules apply

## Output: confidence-tagged candidate list

Present to the user before proposing any diffs:

```markdown
## Learning: <one-line statement>

### High-confidence candidates (propose diff)
- `<skill1>` — at `<file>:<line>` — direct match, same topic + activity
- `<skill2>` — at `<file>:<line>` — direct match

### Medium-confidence candidates (ask before proposing)
- `<skill3>` — at `<file>:<line>` — adjacent topic; rule might apply with adjustment

### Low-confidence (mentioned for awareness, no proposal)
- `<skill4>` — keyword present but in unrelated context

### Memory candidate (cross-cutting principle?)
- Yes / no. If yes, suggested path: `~/.claude/memory/feedback_<slug>.md`

**Proceed with high-confidence diffs? Approve / edit / skip each.**
```

Per-candidate approval (not batch) — small changes are easy to OK individually; bundled changes force all-or-nothing decisions.

## Scope control

Default: search **only the current repo**. Most learnings are repo-local.

Add `--cross-repo` flag when:
- The learning is clearly meta (naming convention, file structure, frontmatter)
- The skills span multiple repos (e.g., a voice rule that applies to social skills in several of your sibling plugins)
- the user explicitly asks ("apply this to all my skills")

Cross-repo propagation: produce one commit per repo. Don't try to atomic-commit across repo boundaries.

## When to skip a candidate

Sometimes a candidate keyword-matches but applying the rule would be wrong. Reasons to skip:
- The skill's context is genuinely different (e.g., `read-book` "summary" mode wants written voice, not spoken)
- The rule has a documented exception (e.g., reading-first density mode in `slide-deck` exempts voice rules)
- Applying it would over-constrain a deliberately flexible area

When skipping, note in the report: *"Considered but skipped: `<skill>` because `<reason>`."* This makes the decision auditable later.

## Frequency heuristic

If the same learning lands in update proposals 3+ times for related skills, it's probably a **principle, not a rule**. Promote to `feedback_*.md` in memory and reference from each affected skill rather than copy-pasting the same text 5 places.

# Versioning — semver for skills

Per-skill `metadata.version` follows semantic versioning. Bumps are small signals, but they matter for "what changed since I last looked at this skill."

## The rules

| Bump | When | Example |
|---|---|---|
| **PATCH** (0.1.0 → 0.1.1) | Clarification, typo fix, minor wording improvement, reference doc update, error-message tweak. Behavior unchanged. | Tightening a description, fixing a broken link, rewording a step for clarity. |
| **MINOR** (0.1.0 → 0.2.0) | New capability — new mode, new reference file, new option, expanded scope. Backward-compatible. | Adding `from-chat` mode to `create-skill`. Adding density modes to `slide-deck`. New `--with-replies` flag on `social-fetch`. |
| **MAJOR** (0.1.0 → 1.0.0) | Breaking change — rename, removed mode, incompatible output format change, removed reference file callers rely on. | Renaming `add-skill` → `create-skill`. Removing the `transcript` mode from `watch-video`. Renaming output JSON keys in `social-fetch`. |

## Pre-1.0 nuance

Most skills start at `0.1.0`. While in 0.x, breaking changes can bump MINOR instead of MAJOR (e.g., `0.1.0` → `0.2.0` for a rename, as we did for `jab-hook`). This signals "still iterating, expect changes." Move to `1.0.0` when:
- The skill has been used successfully ~10+ times
- The interface is stable
- the user explicitly says "lock it in"

After `1.0.0`, the standard rules apply strictly.

## What NOT to bump

- **Rewording the same idea** without changing behavior → don't bump (just commit)
- **Adding a comment** → don't bump
- **Fixing a typo in a non-load-bearing section** → don't bump (or PATCH if you must)

Bumps should be meaningful. If every commit bumps, the version stops carrying information.

## Multi-file changes

When an update touches multiple files within the same skill (SKILL.md + a references/ file), bump the version once for the skill — not per file.

When an update spans multiple skills (cross-skill propagation), bump each affected skill independently per its own change scope. Example:
- Slide-deck adds a new voice rule (MINOR for slide-deck)
- Jab-hook adopts the same voice rule (PATCH for jab-hook — clarification, not new behavior)

## Where the version lives

```yaml
---
name: <skill-name>
description: <...>
metadata:
  version: 0.2.0          # ← here
---
```

If `metadata.version` is missing, treat as `0.1.0` and add it explicitly during the next update.

## What to put in the commit message

Mention the bump:

```
slide-deck: add ppt + export modes (0.1.0 → 0.2.0 — MINOR)

<details>
```

This makes the changelog grep-able:

```bash
git log --oneline | grep -E "MAJOR|MINOR|PATCH"
```

## Bumping versions on rename

Cross-skill renames (e.g., `video-watch` → `watch-video`, `add-skill` → `create-skill`) are MAJOR by definition — they break callers. Bump accordingly.

For internal-only renames (a section heading inside SKILL.md, never referenced externally), no bump needed.

## When you're not sure

Default to PATCH. It's better to undersell a change than oversell.