---
name: skill-capture
description: >
  Turn a recurring in-session workflow into a reusable Claude Code skill. Load this the
  moment you notice you have run the SAME multi-step sequence (same ordered steps or
  commands, small variation allowed) about three times in the current session, or when
  open candidates are waiting in .credo/skill-candidates.md at session start or resume. It
  is heuristic and in-session only - no persistent counter, no tracking backend. Mode-gated
  like the audit nit-disposition policy: autonomous mode NEVER builds a skill (it only
  appends a candidate note and keeps working), active / passive / default propose the
  capture via the Ask tool and build only on an explicit GO. Applies inside subagents too,
  where the safest branch (autonomous: candidate note only, never ask, never build) is the
  default whenever the mode cannot be determined.
---

# skill-capture - recurring workflow becomes a reusable skill

When the same ordered, multi-step workflow keeps recurring in a session, that repetition is
a signal: the workflow is worth capturing once as a Claude Code skill so it need not be
re-derived every time. This skill governs how credo notices that repetition and, only with
the right permission, turns it into a discoverable skill - without inventing any new
infrastructure.

## Detection heuristic (in-session, no backend)

Detection is purely heuristic and lives entirely in the current session's context. There is
NO persistent counter, NO tracking file that increments, NO new infrastructure. You notice
the pattern the same way a person would:

- A candidate is the SAME multi-step sequence - the same ordered steps or commands, small
  variation allowed (different arguments, paths, or names) - that you have carried out about
  three times in the running session.
- One-off actions and trivial single commands are not candidates. The value is in a
  multi-step ordered sequence that you would otherwise reconstruct from scratch each time.
- Detection resets with the session. This skill does not try to remember across sessions via
  a counter; cross-session memory lives only in the two `.credo/` files below, which are
  written when a pattern is actually noted or built, never as a running tally.

## Mode gating (hard guarantee)

How you act on a detected candidate depends strictly on the session mode, mirroring the
audit skill's nit-disposition policy (presence modes ask, autonomous acts on a documented
default). The mode comes from the session-mode inject line.

**Safe default when the mode is not determinable.** A subagent gets no session-mode inject
line, so its mode is often unknown. When you cannot determine the mode, apply the SAFEST
branch = the autonomous behavior below: append a candidate note only, never ask, never
build. This is the same principle by which safety rules always take their strictest reading
inside subagents - an unknown mode must never fall through to the ask-and-build branch.

- **Autonomous mode - NEVER build a skill, no matter how often the pattern recurs.** A skill
  needs an explicit user GO, which an autonomous run never has; a build-on-detection rule
  would be a showstopper. Instead, append ONE candidate note to
  `.credo/skill-candidates.md` and continue the actual work normally. Never block, never ask,
  never create the skill. The note is what lets a later presence-mode session pick it up.
- **Active / passive / default with the user present (main agent, mode determinable) -
  propose, never auto-create.** Explain the recurring pattern briefly and use the Ask tool to
  propose capturing it as a skill, with a clear recommendation (default: capture, when the
  pattern is genuinely reusable). Build the skill ONLY after an explicit GO. Without a GO,
  either drop it or record it as an open candidate (below) - never create a skill unasked.
  This ask-and-build branch requires that the mode is actually determinable and the user is
  reachable; an unknown mode takes the safe default above, not this branch.

This gating is the load-bearing guarantee: autonomous work is never derailed into building a
skill, and no skill is ever created without the user's explicit GO.

## Where the generated skill goes (standard discovery path)

A generated skill MUST land on a real Claude Code skill-discovery path, or Claude Code will
never find it. Derive the scope from the workflow, propose the location via Ask, and let the
user confirm or change it:

- **Repo-specific workflow** (only meaningful in this project) -> `<repo>/.claude/skills/`.
- **Generally useful workflow** (useful across projects) -> `~/.claude/skills/`.

Do NOT place a generated skill under `.credo/skills/` or anywhere else outside the discovery
paths - a plain `.credo/skills/` folder is NOT scanned for skills, so a skill written there
would silently never load. `.credo/` holds only the two tracking files below, never the
generated skill itself.

## Origin marking (all three, together)

Every skill built from a recurring workflow carries all three origin markers, so it is
always recognizable as credo-generated and traceable back to its pattern:

1. **Name prefix `credo-<name>`** - the skill's `name` (and folder) starts with `credo-`, so
   generated skills group visibly in the skills list. Example: `credo-hotfix-pr`.
2. **Frontmatter marker plus a dated body note** - each generated `SKILL.md` frontmatter
   carries `origin: credo-repetition`, and the body opens with a short comment naming the
   source, for example: "Built from a recurring workflow on 2026-07-19." Keep the note to
   one line.
3. **Register line** - append one line per built skill to `.credo/generated-skills.md` (see
   below).

## The two `.credo/` files (append-only, created on first use)

Both files live at the root of `.credo/` (resolve `.credo` via the repo root, same as every
other credo file), are plain append-only Markdown, and are created the first time they are
needed - do not pre-create them. Like the rest of `.credo/**` they are git-excluded by
default, so they stay local unless the project opted into `.credo` versioning.

- **`.credo/generated-skills.md`** - the register of skills that were actually BUILT. One
  line per built skill: name, path, date, and the observed pattern.
- **`.credo/skill-candidates.md`** - patterns that were SEEN but not built. Autonomous mode
  appends here. Active / passive read it at session start and offer the open candidates
  (below). Append-only: to resolve a candidate you APPEND a resolution line referencing it
  (built or discarded), you do not rewrite earlier lines. An "open" candidate is one with no
  later resolution line.

### Example line format

`.credo/generated-skills.md` (one line per built skill):

```
- 2026-07-19 | credo-hotfix-pr | ~/.claude/skills/credo-hotfix-pr/SKILL.md | pattern: branch -> edit -> commit -> push -> gh pr create, seen ~3x
```

`.credo/skill-candidates.md` (a candidate, then its later resolution):

```
- 2026-07-19 | candidate: release bump (edit plugin.yaml + plugin.json version, validate JSON), seen ~3x | scope: repo (marcel-bich-claude-marketplace) | status: open
- 2026-07-20 | resolved candidate 2026-07-19 (release bump): built as credo-version-bump (<repo>/.claude/skills/credo-version-bump/SKILL.md)
```

A discarded candidate resolves the same way: `... | resolved candidate <date> (<short>): discarded - <reason>`.

## Session-start loop (presence modes)

In active and passive mode, at session start or resume, read `.credo/skill-candidates.md`
and gently offer any OPEN candidates (those without a resolution line) - exactly the tone of
the common-core "Soft old-item reminder": surface a few, recommend, then let it go. No hook,
no compulsion, no pushing back against the current work; the only goal is that a candidate
noted by an earlier (often autonomous) session is not forgotten. On a GO, build it and
append both the register line and a candidate resolution line; on a decline, append a
discarded resolution line. Autonomous mode does not run this offer loop - it only ever
appends candidates, never builds.

## KISS / YAGNI

This feature is deliberately behavior-only. It needs NO new shell script, NO tracking
backend, and NO config options - just this skill's text plus the two Markdown files that
Claude maintains by hand. Do not add a counter, a hook, or a config key for it unless a
concrete need actually appears (YAGNI). When you do build a generated skill, keep the skill
itself minimal and follow the normal skill conventions.

## dogma-first

Where dogma already governs a concern (git rules, language, versioning, linting) for the
generated skill or its files, follow dogma first and treat credo rules as fallback only.
DOGMA-PERMISSIONS always take precedence.