skill-plus

name	skill-plus
description	agent-plus | Mine the Claude Code session log to find commands the user keeps typing by hand, then scaffold them into proper Claude skills under `.claude/skills/<name>/`. Read-only audit of existing skills against the framework contract via `list`. Cross-source feedback aggregator joining `skill-feedback` ratings with implicit session-mining failure signals via `feedback`. Promote project-local skills to a `<user>/agent-plus-skills` marketplace via `promote`. Stdlib Python, local-only, no network.
when_to_use	Trigger when the user says "I keep doing this", "I've done this three times", "I keep running the same command", "make this repeatable", "I do this every PR", "make this a skill", "what skills should I have", "audit my skills", "scaffold a skill for X", "promote this skill to my marketplace", "show me what I do repeatedly", "feedback on the framework", "is this skill any good", "session mining", "what's in my session log", "what could be a routine", "what do I do on a schedule", "what should I automate", "turn this into a routine", "I do this every morning", "what should I cron". For cadence questions surface `skill-plus propose --kind all` (routine = schedulable, habit = diffuse repeat). Also trigger AFTER a stretch of repetitive Bash work where the user expresses friction — surface `skill-plus propose` to show the candidates that have already been mined.
allowed-tools	Bash(skill-plus:*) Bash(python3 *skill-plus*:*)

skill-plus

The fifth universal primitive of agent-plus. Turns repeated Bash patterns from real Claude Code sessions into project-scoped Claude skills, audits the skills you already have, and feeds back two streams of evidence (explicit ratings + implicit failure signals) into one quality loop.

The binary lives at ${CLAUDE_SKILL_DIR}/../../bin/skill-plus; the plugin auto-adds bin/ to PATH, so call it as skill-plus.

When to reach for this

Mining loop:

# First time in a project — grant consent (one-shot per project)
skill-plus scan --accept-consent

# Show ranked candidates from the candidate log
skill-plus propose --pretty

# Cadence lens: schedulable routines vs diffuse habits (from the same scan)
skill-plus propose --kind all --pretty
skill-plus routine --adopt <id>     # you set this routine up -> stop suggesting it
skill-plus routine --dismiss <id>   # not useful -> de-rank

# Scaffold the top candidate into a real skill
skill-plus scaffold railway-probe \
  --from-candidate 8ad12e3f9be1 \
  --description "One-shot Railway error probe across services" \
  --when-to-use "Triggers on 'is staging green' / 'why is api 500ing' / 'check railway errors'" \
  --do-not-use-for "deploys; env-var management; logs over 1h windows"

# Make scanning continuous (weekly)
skill-plus install-cron --frequency weekly

Audit + feedback loop:

# What's in this project, scored against the contract
skill-plus list --pretty

# Where are agents falling back from existing plugins? Where's the discoverability gap?
skill-plus feedback --pretty

# Single skill deep-dive
skill-plus feedback --skill repo-analyze --pretty

Marketplace lifecycle:

# Default is dry-run — see the plan
skill-plus promote railway-probe --to osouthgate/agent-plus-skills

# Ship it — copies into the marketplace clone, mutates marketplace.json#skills,
# removes the project-local copy unless --keep-local
skill-plus promote railway-probe --to osouthgate/agent-plus-skills --no-dry-run

Killer command

skill-plus scaffold <name> --from-candidate <id> — turn a mined session pattern into a complete .claude/skills/<name>/ skeleton (SKILL.md + POSIX + Windows launchers + stdlib Python entry with envelope helpers, redactor, layered env resolver) with the killer command pre-filled from the evidence. One call replaces the blank-page boilerplate that is the friction every skill author hits.

Do NOT use this for

• Logging skill ratings — that's skill-feedback's job. skill-plus feedback is a read-side aggregator over skill-feedback's output, not a competing logger.
• Diff summarization — diff-summary.
• Repo orientation — repo-analyze.
• Generating skills from a stack ("I have postgres, give me a postgres skill") — that's shape-matching, not evidence. Mine the session log instead.
• Anything that requires reading session content beyond Bash tool calls — by design, only Bash invocations are clustered. Other tool types are out of scope for v0.

Safety rules

• No transcript ever leaves the machine. All processing local; no network calls.
• Consent is mandatory. First scan in a project requires --accept-consent or prior interactive grant; cron consent is captured at install time. Recorded in ~/.agent-plus/skill-plus/consent.json. Without consent, scan returns rc=2 and exits clean — never reads the log.
• Secret redaction runs before write. Every command is scrubbed for known token patterns (GitHub, AWS, Anthropic, Langfuse, Stripe, OpenAI-style, OpenRouter, Supabase, Sentry, Google, Slack, Discord, JWTs, Bearer, Authorization, connection strings, --token=/--password=/--secret= argv) before it lands in candidates.jsonl. Display, on-disk persistence, and --from-candidate seeding all read from the already-redacted store.
• Read-only by default. propose, list, feedback never write. scaffold writes only inside .claude/skills/<name>/ and refuses to overwrite without --force. promote --no-dry-run is the only command that touches another repo, and it's gated behind explicit opt-out of the dry-run default.
• Cross-project mining is opt-in. --all-projects requires the flag; default scope is the current project only.

Architecture

bin/skill-plus is a stdlib Python 3.9+ launcher — no pip installs, no requirements. Subcommand handlers live in bin/_subcommands/<name>.py and are loaded via importlib.SourceFileLoader so each parallel-developed slice owns its own file (no merge conflicts on the dispatcher). Shared helpers (project_state_root, scrub_text, _git_toplevel, session_files_for_project, has_consent_for, etc.) are injected into each subcommand module's namespace at load time.

Storage precedence mirrors skill-feedback: SKILL_PLUS_DIR env override → <git-toplevel>/.agent-plus/skill-plus/ → <cwd>/.agent-plus/skill-plus/ → ~/.agent-plus/skill-plus/. Per-user config + consent always live in ~/.agent-plus/skill-plus/.

Envelope contract: tool: {name, version} top-level on every payload. --output PATH offloads the full JSON to disk and returns a compact summary (payloadPath, bytes, payloadKeys, payloadShape). --shape-depth 1|2|3 controls how deep the shape recurses. Matches the repo-analyze / diff-summary / skill-feedback shape exactly.