# Craft Skills And Memories

> Use when creating a skill or memory, when one fails in practice, or when the user reports one misbehaving or stale.

- Skill: `vivswan/craft-skills-and-memories` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add vivswan/craft-skills-and-memories`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vivswan/craft-skills-and-memories/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: SEE LICENSE IN LICENSE.md
- Author: Vivswan (https://skillmd.com/u/vivswan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vivswan/craft-skills-and-memories

---


# Craft Skills and Memories

One skill for both ends of the lifecycle of an agent's instruction sources: creating skills and memories worth keeping, and repairing them when they fail in practice.

A broken skill or a stale memory is a bug. Working around it and moving on re-breaks the next session.

Scope:

- **Skills are general-purpose.** Nothing in a skill should be project-specific. A fact that only holds for one project belongs in that project's own docs or memories, not in the skill.
- **Memories may be project-specific or common.** Create and fix a memory at the scope it belongs to: a project memory in that project's store, a common memory in the shared store.

## The Quality Bar (creating and fixing alike)

- **Example-, scenario-, or concept-led, never quote-led.** The concrete specimen (the failing command, the corrected block, a worked scenario) recalls far better in a future session than abstract explanation or the user's verbatim words.
  - Structure each entry specimen-first: what happened and where, then the rule it taught, then the boundary or exceptions.
  - Keep a short verbatim phrase only when the exact wording IS the directive (a ban, a naming rule). Otherwise paraphrase into the rule.
  - When touching an old quote-led entry, retrofit it.
- **Descriptions are triggers**: short, "Use when ...", stating the one moment the thing should fire, never summarizing contents. A summary-shaped description is an activation bug.
- **Skills** carry runnable copy-paste blocks and worked examples a cold agent can follow.
- **A skill roster stays lean and disjoint.** The design conditions for creating, combining, and splitting skills:
  - Every firing moment has exactly one home: a skill states its specific moments, and triggers across the roster are pairwise disjoint. An overlap is a defect, resolved by combining or sharpening, never tolerated (this skill's create-and-fix lifecycle is such a combination: its moments share one home, one reader).
  - Fewer skills beats more: combine two skills that serve the same reader at the same moment.
  - No skill becomes extremely complex or big: split by firing moment when one grows. A complex skill never absorbs a sibling even when triggers overlap; sharpen the descriptions instead.
  - Skimmable throughout: short front-loaded paragraphs, no text blobs (the example-led rule above governs content order); readability for the reader outranks style rules, and accuracy rules always bind.
  - Form follows the change in any section: no mandated format beyond this bar, never a visual plus prose re-explaining it, programmer register (the `/natural-writing` bullet below states when that skill applies to prose).
  - No backwards compatibility, folders included: splits, merges, and retirements are normal changes, with every deletion audited per the `/never-twice` skill (Deleting a Guard). A compatibility contract the hosting repo declares (such as published install paths) still binds folder moves there.
- **Memories** hold one fact per file, record the why, convert relative dates to absolute, and link related memories. A wrong memory gets deleted, not patched around.
- When rewriting prose, apply the `/natural-writing` skill if it is present and invocable. If your harness lets only the user invoke it, suggest they run `/natural-writing` rather than silently skipping the step.

## When to Apply

Creating:

- "Save this as a memory" / "make this a skill" / "remember this"
- The decision is made to encode a lesson or workflow for future sessions (deciding the response to a correction is `/never-twice`'s job; its rung 3 hands off here)

Fixing:

- A documented flag, command, or file in a skill no longer exists
- A skill's copy-paste block breaks in a reproducible way
- A skill's extraction or verification rule misses what it is supposed to catch
- A recalled memory names a file, flag, or workflow that no longer exists or was superseded
- The user says a skill or memory is not working properly

## Creating

1. **Check for an existing home first.** A skill or memory that already covers the topic gets updated; duplicates drift apart.
2. **Pick skill vs memory.**
   - General-purpose behavior any user could install: skill.
   - Personal or project fact, policy, or preference: memory, at the right scope.
   - A skill that encodes a personal workflow rather than an auto-detectable task should be explicit-invocation-only: `disable-model-invocation: true` in the frontmatter, and `policy.allow_implicit_invocation: false` in `agents/openai.yaml` for Codex.
3. **Write it to the quality bar above**, with the triggering incident as the specimen.
4. **Wire it in**: a skill follows its repository's authoring checklist (manifests, catalog, checks); a memory gets its index line.
5. **Run the gates** where they exist (repo checks, review). For a memory, re-read it asking "will a cold session act correctly from this?"

## Fixing

### 1. Rule out transient causes

Backend outages, sandbox restrictions, and local tool configuration are not skill defects. Only a failure whose root cause is the instructions themselves qualifies.

### 2. Finish the current task first

Work around the broken step to complete what the user actually asked for. The fix comes after, not instead.

### 3. Fix it at its canonical source

- Skill in its authoring repository: edit the affected sources directly (`SKILL.md`, `references/`, `scripts/`).
- Installed or vendored skill copy you are authorized to edit (e.g. a personal skills directory): edit that copy, and tell the user the upstream source still carries the defect if one exists.
- Memory: edit the memory file where it lives and keep its index line in sync. A memory that is wrong, as opposed to merely stale, gets deleted, not patched around.
- Not authorized to write: report the defect and your proposed fix to the user instead.

### 4. Fold the fix in, don't append a note

Rewrite the affected step so it is correct as written and meets the quality bar. Keep copy-paste blocks runnable. A one-off warning bolted to the end leaves the broken instructions in place. A rewrite that deletes rules follows the deletion audit in the `/never-twice` skill (Deleting a Guard).

**Code first for mechanical failures.** Where each kind of fix lands:

- A skill's script-backed **mechanical** behavior fails in practice (a probe misreads, a command mis-parses, an edge case crashes): the fix lands in the script, plus a regression test that reproduces the incident.
- **Incident-warning** prose is the scoped reservation: trap narratives and priors stay judgment-lesson-only, because the script embodies the mechanism.
- Public **contract** documentation (CLI shapes, schemas, output fields) is different: it moves together with the interface change it describes. Where a drift gate pins doc to source, the gate enforces exactly that pairing.
- **Documentation-only** defects (activation metadata, invocation examples, workflow prose) fix in their actual source, never by touching a script that was not the failure.

Why code first: a trap folded into a tested script cannot re-fire. A trap folded into prose regrows the catalog: each incident adds a warning paragraph, the file swells, and a future session hand-rolls the broken step anyway.

Worked case: a fleet-monitoring skill accumulated shell-probe trap prose (word-splitting, self-matching greps, a missing `timeout` binary) until the probes moved into tested scripts and the prose shrank to the judgment layer.

### 5. Put the edit through the normal gates

A skill or memory edit is a change like any other: run whatever checks and review process govern the place it lives. Where none exist (e.g. a plain installed copy), at least re-run the failing scenario to confirm the rewritten instructions work.

## Worked Examples

**A creation.** The user corrects the agent twice for hard-wrapping commit messages at 72 columns.

- That is a memory, not a skill: personal policy, applies across repos, nothing installable.
- Write `commit-message-rules.md` in the common store with the correction as the specimen and the why, then add its index line.
- Example-led, not quote-led: it records the rule and a concrete before/after, not the user's exact words.

**A skill defect.** While following a review skill, `claude -p --output-format stream-json` exits with an error and an empty output file.

1. Transient? No: it reproduces every run, and `claude --help` shows `--output-format stream-json` requires `--verbose`. The root cause is the skill's documented command.
2. Finish the review by re-running with `--verbose` added.
3. The skill's canonical source is a local checkout of its authoring repo: edit the copy-paste block in its `SKILL.md` to include `--verbose`.
4. The fix goes into the block itself, so it stays runnable as written; no footnote saying "note: also pass --verbose".
5. Run that repo's checks and include the edit in the same change set for review.

**A stale memory.** A recalled project memory says deploys go through `make release`, but the Makefile renamed the target to `make publish` months ago.

1. Verify against the current repo: the memory is stale, not the build.
2. Finish the deploy with the real target.
3. Update the memory file in that project's store (and its index line) to name `make publish`, keeping the rename as the concrete example.

**Not a defect.** The same command fails once with a backend overload error and succeeds on retry. That is transient; finish the task and leave the skill alone.

## Using Skills

Fit is judged per invocation. When an invoked skill's guidance does not fit the task at hand, skip it (wholly or a specific rule) and tell the user why at the point of the decision.

- Never follow a skill mechanically against the task's needs.
- Never ignore one silently.
- Standing rules the user has set (e.g. a commit gate) still hold; this covers guidance that genuinely conflicts with the work.

## Reporting

Tell the user what you created or what failed, the root cause, and what changed in the skill or memory, separately from the outcome of their original task.