JPeetz/agent-skills / skills/skill-development/skill-lifecycle-foundry
skill-lifecycle-foundry
VerifiedUse 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.mdfrom 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
descriptionand 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
| Operation | Action |
|---|---|
| Mine | python3 scripts/scan_sessions.py <archive> — count workflow-intent repeats |
| Draft | write_file <repo>/<slug>/SKILL.md with frontmatter + canonical body |
| Personalize | Rewrite examples/phrasing to the local user + tools |
| Generalize | Redact secrets, paths, and facts; make examples portable |
| Validate | scripts/validate_skill.py <skills-dir> → "valid": true |
| Release | Walk references/release-checklist.md |
Procedure
Each step ends with a checkable completion criterion.
-
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.
-
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. -
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.
-
Draft the
SKILL.md. Create<repo>/<slug>/SKILL.md(slug = lowercase-kebab folder name). Write frontmatter (namematching the folder,description≤60 chars ending in a period,version,license,author,platforms, ametadata.tagsblock) and the canonical body sections. Completion: frontmatter matches the folder, and the body has all canonical sections. -
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.
-
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. -
Document references. Add
references/sources.md(one line per source + URL) and push any domain-heavy content into dedicated reference docs so theSKILL.mdstays fair. Completion: every reference is sourced and referenced from the body. -
Package. Add
LICENSE,CHANGELOG.md, andevals/evals.jsonnext to it. Completion: SKILL.md, LICENSE, CHANGELOG.md, evals/, references/ exist. -
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 emptyissueslist. -
Release review. Walk the release checklist when the skill ships public. Completion: every checklist line is satisfied before publication.
Pitfalls
- Hardcoded absolute paths.
SKILL.mdfiles 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
descriptionsays 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
nameequals the folder slug;descriptionis ≤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, andreferences/sit besideSKILL.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": truewith no issues.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 467k | Updated | Claude CodeCodex | Verified | Install |
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |