Skip to content

JPeetz/agent-skills / skills/skill-development/skill-lifecycle-foundry

skill-lifecycle-foundry

Verified

Use this skill when mining, authoring, personalizing, or generalizing agent skills.

Skill Lifecycle Foundry

The agent-skill lifecycle is a loop: you mine real usage for repeated workflows, author those into SKILL.md files, personalize them to the local user's tools and phrasing, generalizing them for public release, and keep them honest through a validation gate. This is the meta-skill that governs that whole loop. It governs the other skills in your inventory, not a single task — it tells you how to discover, write, tune, and ship them safely.

It ships one small, optional executable — scripts/scan_sessions.py — a deterministic first-pass miner for the mining step. It is stdlib-only and safe to run on any archive; the rest of the skill is procedure and templates, because session layouts vary too much for a bigger script to be trustworthy.

When to Use

Use this skill when you want to:

  • Mine an agent session history, memory archive, or repo history for recurring workflows that deserve their own skill file.
  • Draft a brand-new SKILL.md from a spec, meeting notes, or a task the developer already performs by hand.
  • Personalize a downloaded, forked, or community skill to the local tools, paths, aliases, and phrasing of the current session.
  • Generalize a private skill so it is safe to publish to a public repo, marketplace, or team without leaking secrets or internal facts.
  • Audit an existing skill for under- and over-triggering and tighten its description and frontmatter.
  • Run a release review against a checklist before a skill goes public.

Don't use for: one-off tasks that are unlikely to recur (those are comments, not skills), writing a skill for a workflow you've never actually run, or any task where a single snippet suffices. If you wouldn't do it twice the same way, it isn't a skill.

Prerequisites

  • Read access to the session/archive sources you intend to mine (session logs, transcripts, memory summaries, repo history).
  • Write access to the target skills root directory. This skill uses a repository-relative skills/ convention; adapt to ~/.agents/skills/, ~/.claude/skills/, or .codex/skills/ as appropriate.
  • No API credentials are needed to operate this meta-skill. Any credential a target skill needs stays inside that skill's own Prerequisites, never here.

How to Run

You run this skill by naming the lifecycle operation you want, for example:

Mine my session history for repeated workflows that should become skills.
Audit this skill; tell me why it doesn't trigger when I say things naturally.
Generalize this private skill so I can publish it.

Because there is no single executable, the procedure below is the run: use the terminal tool to find the archive trees, read_file sessions, and run the validation gate on any skill you author or change.

Quick Reference

OperationAction
Minepython3 scripts/scan_sessions.py <archive> — count workflow-intent repeats
Draftwrite_file <repo>/<slug>/SKILL.md with frontmatter + canonical body
PersonalizeRewrite examples/phrasing to the local user + tools
GeneralizeRedact secrets, paths, and facts; make examples portable
Validatescripts/validate_skill.py <skills-dir> → "valid": true
ReleaseWalk references/release-checklist.md

Procedure

Each step ends with a checkable completion criterion.

  1. Scope the mine. Enumerate the session/archive sources (logs, transcripts, memory, repo history) that record repeated work. Completion: a named list of source paths to scan.

  2. Run the repeat detector. Run python3 scripts/scan_sessions.py <archive_root> in the terminal to count how often each intent keyword recurs across distinct files. Pair the mechanical count with a close read: a keyword may appear often yet be one trivial action. Completion: a shortlist of candidate workflows, each with the session/offset evidence where it repeats.

  3. Rate each candidate. Mark each as personal (local-only), publishable (safe to generalize), or skip (too trivial or already covered). Completion: every candidate has a decision.

  4. Draft the SKILL.md. Create <repo>/<slug>/SKILL.md (slug = lowercase-kebab folder name). Write frontmatter (name matching the folder, description ≤60 chars ending in a period, version, license, author, platforms, a metadata.tags block) and the canonical body sections. Completion: frontmatter matches the folder, and the body has all canonical sections.

  5. Personalize where needed. If this is an existing or community skill, rewrite its examples and phrasing to the local user's tools, aliases, and paths — but keep secrets out and keep paths portable. Completion: the skill reads as the user, not a boilerplate.

  6. Generalize for release. If publishing, sweep the skill for private paths, hostnames, keys, names, quotes, and internal facts; neutralize or redact each. Completion: a secret/pattern sweep of the file returns nothing outside references/sources.md.

  7. Document references. Add references/sources.md (one line per source + URL) and push any domain-heavy content into dedicated reference docs so the SKILL.md stays fair. Completion: every reference is sourced and referenced from the body.

  8. Package. Add LICENSE, CHANGELOG.md, and evals/evals.json next to it. Completion: SKILL.md, LICENSE, CHANGELOG.md, evals/, references/ exist.

  9. Run the gate. Execute scripts/validate_skill.py <skills-dir>; fix any frontmatter or structure issue and re-run until "valid": true. Completion: the validator reports valid and an empty issues list.

  10. Release review. Walk the release checklist when the skill ships public. Completion: every checklist line is satisfied before publication.

Pitfalls

  • Hardcoded absolute paths. SKILL.md files that embed machine-specific absolute home-directory paths break on other machines. Keep paths repo-relative or ~-based.
  • Secret leaks. A private key, hostname, or account name is ink that can't be unprinted. Sweep before release and never tell it later.
  • Runaway body length. A >500-line body is a warning sign. Keep the frontmatter and quick-reference flat; move depth to references.
  • Trigger drift. A skill whose description says nothing about when to use it is a skill that never learns. Keep the description crisp and pointing.
  • Silently rewording others' skills. When personalizing a skill you did not write, keep the blame of changes visible/reviewable.

Verification

  • Frontmatter name equals the folder slug; description is ≤60 characters and ends in a period.
  • Body sections appear in the canonical order: When to Use, Prerequisites, How to Run, Quick Reference, Procedure, Pitfalls, Verification.
  • LICENSE, CHANGELOG.md, evals/evals.json, and references/ sit beside SKILL.md.
  • A scan for sk-+24-char tokens, lin_api_, and absolute path patterns across the released file returns nothing leaked.
  • scripts/validate_skill.py <skills-dir> prints "valid": true with no issues.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall