From 2156b8d0656e0ff4638129cd20137bb482097aed Mon Sep 17 00:00:00 2001 From: joo <14088938+sungizhou@user.noreply.gitee.com> Date: Mon, 8 Jun 2026 02:31:52 +0800 Subject: [PATCH 1/3] Add meta-skill --- README.md | 1 + skills/planning/meta-skill/SKILL.md | 91 +++++++++++++++++++ .../meta-skill/references/design-brief.md | 39 ++++++++ .../references/quality-checklist.md | 57 ++++++++++++ 4 files changed, 188 insertions(+) create mode 100644 skills/planning/meta-skill/SKILL.md create mode 100644 skills/planning/meta-skill/references/design-brief.md create mode 100644 skills/planning/meta-skill/references/quality-checklist.md diff --git a/README.md b/README.md index c311df8..0b9d524 100644 --- a/README.md +++ b/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. diff --git a/skills/planning/meta-skill/SKILL.md b/skills/planning/meta-skill/SKILL.md new file mode 100644 index 0000000..f5bf321 --- /dev/null +++ b/skills/planning/meta-skill/SKILL.md @@ -0,0 +1,91 @@ +--- +name: meta-skill +description: Design, create, audit, and refine Codex skills with careful evaluation, competitive research, a concise design brief, and a distinctive skill identity. Use when Codex 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 Codex 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 Codex 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 the folder with the local skill initializer when available. Prefer: + +```bash +python3 /Users/huangzhou/.codex/skills/.system/skill-creator/scripts/init_skill.py --path +``` + +Add `--resources scripts,references,assets` only for resource directories the skill truly needs. Pass `--interface display_name=...`, `--interface short_description=...`, and `--interface default_prompt='Use $skill-name to ...'` when creating UI metadata. + +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 Codex 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: + +```bash +python3 /Users/huangzhou/.codex/skills/.system/skill-creator/scripts/quick_validate.py +``` + +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 `skill-creator` as the baseline for general Codex skill 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 Codex'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 `skill-creator`, 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 accomplish by being , unlike which . +``` + +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. diff --git a/skills/planning/meta-skill/references/design-brief.md b/skills/planning/meta-skill/references/design-brief.md new file mode 100644 index 0000000..08ea859 --- /dev/null +++ b/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 accomplish by being , unlike which . +``` + +## 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: diff --git a/skills/planning/meta-skill/references/quality-checklist.md b/skills/planning/meta-skill/references/quality-checklist.md new file mode 100644 index 0000000..a57f548 --- /dev/null +++ b/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 Codex 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 `quick_validate.py` against the final skill folder. +- Inspect `agents/openai.yaml` if present; `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. From 0e50bd7cf9d0daa5bd82acfd4302b4def2f4b776 Mon Sep 17 00:00:00 2001 From: joo <14088938+sungizhou@user.noreply.gitee.com> Date: Mon, 8 Jun 2026 02:35:36 +0800 Subject: [PATCH 2/3] Use portable skill-creator paths --- skills/planning/meta-skill/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/planning/meta-skill/SKILL.md b/skills/planning/meta-skill/SKILL.md index f5bf321..cae85dc 100644 --- a/skills/planning/meta-skill/SKILL.md +++ b/skills/planning/meta-skill/SKILL.md @@ -23,7 +23,7 @@ Use this skill to turn a repeated workflow, domain practice, or tool integration 8. Initialize the folder with the local skill initializer when available. Prefer: ```bash -python3 /Users/huangzhou/.codex/skills/.system/skill-creator/scripts/init_skill.py --path +python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/init_skill.py" --path ``` Add `--resources scripts,references,assets` only for resource directories the skill truly needs. Pass `--interface display_name=...`, `--interface short_description=...`, and `--interface default_prompt='Use $skill-name to ...'` when creating UI metadata. @@ -33,7 +33,7 @@ Add `--resources scripts,references,assets` only for resource directories the sk 11. Validate the folder before delivery: ```bash -python3 /Users/huangzhou/.codex/skills/.system/skill-creator/scripts/quick_validate.py +python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" ``` 12. For complex skills, forward-test with realistic prompts and revise based on what the skill failed to make obvious. From 770b905086cf1bc5e08cbdc937c2a50368efcaa0 Mon Sep 17 00:00:00 2001 From: joo <14088938+sungizhou@user.noreply.gitee.com> Date: Mon, 8 Jun 2026 02:44:41 +0800 Subject: [PATCH 3/3] Generalize meta-skill for agent skills --- skills/planning/meta-skill/SKILL.md | 26 ++++++------------- .../references/quality-checklist.md | 6 ++--- 2 files changed, 11 insertions(+), 21 deletions(-) diff --git a/skills/planning/meta-skill/SKILL.md b/skills/planning/meta-skill/SKILL.md index cae85dc..67e0b0e 100644 --- a/skills/planning/meta-skill/SKILL.md +++ b/skills/planning/meta-skill/SKILL.md @@ -1,11 +1,11 @@ --- name: meta-skill -description: Design, create, audit, and refine Codex skills with careful evaluation, competitive research, a concise design brief, and a distinctive skill identity. Use when Codex 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 Codex capability with a clear point of view. +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 Codex 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. +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 @@ -20,21 +20,11 @@ Use this skill to turn a repeated workflow, domain practice, or tool integration - `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 the folder with the local skill initializer when available. Prefer: - -```bash -python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/init_skill.py" --path -``` - -Add `--resources scripts,references,assets` only for resource directories the skill truly needs. Pass `--interface display_name=...`, `--interface short_description=...`, and `--interface default_prompt='Use $skill-name to ...'` when creating UI metadata. +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 Codex 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: - -```bash -python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_validate.py" -``` +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. @@ -50,15 +40,15 @@ python3 "${CODEX_HOME:-$HOME/.codex}/skills/.system/skill-creator/scripts/quick_ - 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 `skill-creator` as the baseline for general Codex skill mechanics. This skill should add product judgment, differentiation, and design coherence on top of that baseline. +- 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 Codex's progressive disclosure model. +- 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 `skill-creator`, identify the missing meta-level behavior, then revise only the parts that make future skill creation more discerning, researched, or distinctive. +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 diff --git a/skills/planning/meta-skill/references/quality-checklist.md b/skills/planning/meta-skill/references/quality-checklist.md index a57f548..97d1ec0 100644 --- a/skills/planning/meta-skill/references/quality-checklist.md +++ b/skills/planning/meta-skill/references/quality-checklist.md @@ -35,7 +35,7 @@ Use this checklist before delivering a created or updated skill. ## Body - The first paragraph explains what the skill enables. -- Instructions are actionable and written for another Codex instance. +- 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. @@ -50,8 +50,8 @@ Use this checklist before delivering a created or updated skill. ## Validation -- Run `quick_validate.py` against the final skill folder. -- Inspect `agents/openai.yaml` if present; `default_prompt` should mention `$skill-name` literally. +- 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.