Add meta-skill

README.md

@@ -105,6 +105,7 @@ Skills are organized by domain under `skills/`. Each skill is a folder with a `S
 - [`tech-debt-portfolio`](skills/planning/tech-debt-portfolio/SKILL.md): Catalog debt, estimate impact, and prioritize with ROI.
 - [`roadmap-prioritization`](skills/planning/roadmap-prioritization/SKILL.md): Score initiatives by impact, effort, and dependencies.
 - [`org-standardization`](skills/planning/org-standardization/SKILL.md): Propose minimal standards and adoption enforcement.
+- [`meta-skill`](skills/planning/meta-skill/SKILL.md): Evaluate, differentiate, and design Codex skills with a concise design brief and distinctive skill identity.
 - [`vendor-evaluation`](skills/planning/vendor-evaluation/SKILL.md): Compare vendors by security, integration, cost, and risks.
 - [`dependency-upgrade-plan`](skills/planning/dependency-upgrade-plan/SKILL.md): Order upgrades, note breaking changes, and plan rollback.
 - [`simple-refactor`](skills/planning/simple-refactor/SKILL.md): Improve naming and structure without behavior changes.

skills/planning/meta-skill/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: meta-skill
+description: Design, create, audit, and refine Agent Skills with careful evaluation, competitive research, a concise design brief, and a distinctive skill identity. Use when an agent needs to make a new skill folder, update an existing skill, write SKILL.md instructions, decide what scripts/references/assets belong in a skill, validate skill metadata, compare similar skills or tools, improve a skill using meta-skill principles, or turn a repeated workflow into a reusable agent capability with a clear point of view.
+---
+
+# Meta Skill
+
+Use this skill to turn a repeated workflow, domain practice, or tool integration into a compact Agent Skill that another agent can use without extra explanation. Treat each skill as a small product: evaluate whether it deserves to exist, study what already solves the problem, write a crisp design brief, then give it a distinct working style and purpose.
+
+## Workflow
+
+1. Evaluate whether a skill is warranted. Prefer creating a skill only when it captures reusable judgment, a repeated workflow, fragile tool knowledge, domain-specific context, or assets/scripts that reduce future work. If the request is better served by a one-off answer, prompt, script, or ordinary documentation, say so and offer the smallest useful alternative.
+2. Clarify the target behavior with concrete prompts the skill should handle. Ask only for missing details that change the skill's scope, destination, or safety profile.
+3. Research nearby solutions before naming or writing. Inspect existing local skills, related plugins, repository conventions, and public or user-provided competitors when available. Identify what they do well, what they omit, and how this skill should differ instead of duplicating them.
+4. Write a short design brief using `references/design-brief.md`. Keep it internal unless the user asks to see it, but let it drive the implementation.
+5. Define the skill's soul: one sentence naming its unique promise, judgment style, and user experience. Use this as a design constraint for scope, examples, tone, resources, and validation.
+6. Choose a lowercase hyphenated skill name under 64 characters. Name the folder exactly after the skill name.
+7. Decide the smallest useful file set:
+   - `SKILL.md` for trigger metadata and essential workflow instructions.
+   - `references/` for longer docs that should be loaded only when relevant.
+   - `scripts/` for deterministic or repeated operations that should not be rewritten each time.
+   - `assets/` for templates, fonts, icons, examples, or other files used in final outputs.
+8. Initialize or create the folder using the best helper available in the current agent environment. If no initializer exists, create the folder manually with a required `SKILL.md` and only the resource directories the skill truly needs. Pass UI metadata such as display name, short description, and default prompt only when the host agent or marketplace supports it.
+
+9. Replace all placeholders. Keep frontmatter to only `name` and `description`; put all trigger conditions in `description`, because the body loads only after the skill triggers.
+10. Write the body as instructions for another agent instance. Use imperative language, compact examples, and explicit references to bundled files only when those files should be read.
+11. Validate the folder before delivery using the relevant platform validator, schema checker, or install test. If no validator exists, inspect frontmatter, resource paths, trigger boundaries, and example prompts manually.
+
+12. For complex skills, forward-test with realistic prompts and revise based on what the skill failed to make obvious.
+
+## Evaluation Principles
+
+- Be conservative about creating new skills. A skill should remove future ambiguity, encode hard-won context, or make a repeated workflow safer and faster.
+- Avoid thin wrappers around common reasoning. If a general instruction is enough, improve the prompt or documentation instead of creating a skill.
+- Separate evaluation from implementation. Decide the user's job, risks, alternatives, and success criteria before editing files.
+- Name risks early: stale external docs, hidden credentials, destructive actions, expensive calls, privacy boundaries, or workflows that require human approval.
+- Prefer narrow excellence over broad vagueness. A memorable small skill is more useful than a generic one that triggers everywhere.
+
+## Competitive Research
+
+- Search available local skills and plugins first. Compare names, descriptions, resource structure, and trigger boundaries.
+- When external research is appropriate and available, inspect comparable tools, repos, docs, marketplace entries, or examples before finalizing scope.
+- Treat the host platform's skill creation guide or validator as the baseline for mechanics. This skill should add product judgment, differentiation, and design coherence on top of that baseline.
+- Capture only the useful delta in the skill itself: what this skill does differently, what it intentionally avoids, and what neighboring skill should be used instead.
+- Do not clone a competitor's structure blindly. Borrow proven patterns, then adapt them to the user's actual workflow and the host agent's progressive disclosure model.
+
+## Design Brief
+
+Before creating or substantially updating a skill, sketch the brief from `references/design-brief.md`. Use it to make tradeoffs explicit: whether to build, what to research, what to exclude, and how to know the skill improved.
+
+If updating this skill itself, apply the same brief recursively: compare it to the closest skill-creation baseline, identify the missing meta-level behavior, then revise only the parts that make future skill creation more discerning, researched, or distinctive.
+
+## Distinctive Soul
+
+Before implementation, write an internal one-sentence identity for the skill:
+
+```text
+This skill helps <user> accomplish <job> by being <distinctive judgment/style>, unlike <nearby alternative> which <limitation or different focus>.
+```
+
+Use the identity to decide what belongs in the skill and what should be excluded. The finished skill does not need to include the sentence verbatim, but its description, workflow, resources, and examples should make the identity legible.
+
+## Delivery Standard
+
+- Explain what changed and why it improves the skill's judgment, usability, or distinctiveness.
+- Mention the closest alternative or competitor considered and how the final skill differs.
+- Keep the final skill usable without reading the design brief, while keeping the brief available for audits and major revisions.
+
+## Authoring Rules
+
+- Keep `SKILL.md` concise. Move optional detail into one-level reference files and name when to open them.
+- Let the skill's unique promise shape every section; remove content that could belong unchanged in any other skill.
+- Prefer resources only when they reduce future work or prevent fragile recreation.
+- Avoid extra documentation such as `README.md`, install guides, changelogs, or process notes unless the user explicitly asks.
+- Use existing local conventions from nearby skills when updating an existing skill.
+- Test every added script by running it at least once, or clearly state why it was not run.
+- Preserve user edits in existing skill folders; patch around them rather than replacing whole files blindly.
+
+## Quality Review
+
+Before finishing, read `references/quality-checklist.md` and apply the checklist. Fix any failure that would stop the skill from triggering, loading, validating, or being useful to a future agent.

skills/planning/meta-skill/references/design-brief.md

@@ -0,0 +1,39 @@
+# Skill Design Brief
+
+Use this brief before creating a new skill or making a substantial update. Keep answers short; the goal is sharper decisions, not ceremony.
+
+## 1. Build Decision
+
+- User job:
+- Repeated or fragile workflow:
+- Why a skill is better than a one-off answer, prompt, script, or normal docs:
+- Risks or approval boundaries:
+
+## 2. Competitive Scan
+
+- Closest local skills or plugins:
+- Closest external tools, docs, repos, examples, or user-provided references:
+- What they do well:
+- What they miss or intentionally optimize for instead:
+
+## 3. Distinctive Soul
+
+Use this sentence:
+
+```text
+This skill helps <user> accomplish <job> by being <distinctive judgment/style>, unlike <nearby alternative> which <limitation or different focus>.
+```
+
+## 4. Scope
+
+- Must do:
+- Must not do:
+- Neighboring skill or tool to use instead:
+- Minimal resource set (`SKILL.md`, `references/`, `scripts/`, `assets/`):
+
+## 5. Validation
+
+- Example prompts that should trigger the skill:
+- Example prompts that should not trigger it:
+- Commands, tests, or forward-tests to run:
+- What would prove the update made the skill better:

skills/planning/meta-skill/references/quality-checklist.md

@@ -0,0 +1,57 @@
+# Skill Quality Checklist
+
+Use this checklist before delivering a created or updated skill.
+
+## Strategic Fit
+
+- The skill is justified by reusable judgment, fragile workflow knowledge, domain context, scripts, references, or assets.
+- A simpler one-off answer, prompt, README, or local script would not serve the user better.
+- A concise design brief exists mentally or explicitly for substantial work, covering the build decision, alternatives, soul, scope, and validation.
+- Important risks are named and handled: stale docs, credentials, destructive actions, privacy, cost, permissions, or required human approval.
+- The skill has a narrow enough scope to be excellent instead of generically helpful.
+
+## Competitive Research
+
+- Existing local skills and relevant plugins have been checked for overlap.
+- Comparable external tools, docs, repos, marketplace entries, or user-provided references have been reviewed when available and useful.
+- The new or updated skill has a clear delta from nearby alternatives.
+- The skill says when to use a neighboring skill or tool instead, if that boundary matters.
+
+## Distinctive Soul
+
+- The skill has a one-sentence identity: who it helps, what job it performs, and what judgment or style makes it different.
+- The frontmatter description, workflow, examples, and resources all reinforce that identity.
+- The skill's closest baseline or competitor is clear enough that the difference is not hand-wavy.
+- Generic advice that could appear unchanged in any other skill has been removed or made specific.
+- The skill feels like a purposeful capability, not a template with a new name.
+
+## Trigger Metadata
+
+- `SKILL.md` frontmatter contains only `name` and `description`.
+- `name` matches the folder name and uses lowercase letters, digits, and hyphens only.
+- `description` says what the skill does and exactly when to use it.
+- Trigger conditions are not hidden only in the body.
+
+## Body
+
+- The first paragraph explains what the skill enables.
+- Instructions are actionable and written for another agent instance.
+- The workflow is shorter than the task it replaces.
+- Examples are concrete, minimal, and directly reusable.
+- Long optional detail lives in `references/`, not inline.
+
+## Resources
+
+- Each resource directory has a clear purpose.
+- Scripts are executable, deterministic, and tested.
+- Reference files are linked directly from `SKILL.md` with guidance on when to read them.
+- Assets are files to copy or use, not documents the model must read.
+- Placeholder example files have been removed.
+
+## Validation
+
+- Run the relevant platform validator, schema checker, or install test against the final skill folder.
+- Inspect platform-specific UI metadata if present; any `default_prompt` should mention `$skill-name` literally.
+- Check for leftover TODO markers or template prose.
+- The final response can say why the skill is better after the update.
+- If the skill changes a risky or complex workflow, forward-test it with a realistic user request.