skill-writing

name	skill-writing
description	Use when creating or upgrading skills in this repository. Covers repository-specific frontmatter rules, progressive disclosure, reference-file strategy, validation, and the quality bar required for production-grade engineering skills.
metadata	{"portable":true,"compatible_with":["Codex","codex"]}

Skill Writing

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, [phone].

Use When

• Use when creating or upgrading skills in this repository. Covers repository-specific frontmatter rules, progressive disclosure, reference-file strategy, validation, and the quality bar required for production-grade engineering skills.
• The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

Do Not Use When

• The task is unrelated to skill-writing or would be better handled by a more specific companion skill.
• The request only needs a trivial answer and none of this skill's constraints or references materially help.

Required Inputs

• Gather relevant project context, constraints, and the concrete problem to solve; load references, scripts only as needed.
• Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

Workflow

• Read this SKILL.md first, then load only the referenced deep-dive files that are necessary for the task.
• Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
• Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

Quality Standards

• Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
• Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
• Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

Anti-Patterns

• Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
• Loading every reference file by default instead of using progressive disclosure.

Outputs

• A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
• Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
• References used, companion skills, or follow-up actions when they materially improve execution.

References

• Use the references/ directory for deep detail after reading the core workflow below.
• Use the scripts/ directory for repository-native automation before inventing new tooling.

Use this skill for repository-native skill authoring. The goal is not to create generic instructional files; it is to encode reusable, high-signal operational knowledge for Codex.

Repository Rules

• Keep SKILL.md under 500 lines. Keep deeper markdown references lean and split them when they become hard to load or maintain.
• Use only validator-approved frontmatter keys: name, description, license, allowed-tools, metadata.
• Make description the trigger: what the skill does and when to use it.
• Put deep detail in references/; keep SKILL.md focused on execution logic.
• Do not add meta-docs inside skills such as README.md or CHANGELOG.md.

Authoring Workflow

1. Define the Reusable Problem

Create or update a skill only if it captures:

• A repeatable workflow.
• A stable architectural or domain pattern.
• A high-risk area where guardrails materially improve outcomes.

Do not create skills for generic programming knowledge or one-off tasks.

2. Choose the Skill Shape

Use one of these structures:

• Workflow skill: step-by-step execution for fragile or sequential work.
• Standards skill: decision rules, checklists, and gates for quality-sensitive domains.
• Domain skill: business concepts, invariants, and recurring implementation patterns.

3. Keep the Core Lean

SKILL.md should contain:

• Scope and activation clues.
• Ordered workflow or decision logic.
• Non-negotiable standards.
• Short checklists.
• References to deeper files.

Move these to references/:

• Large examples
• Review templates
• Detailed schemas
• Long checklists
• Topic-specific deep dives

4. Encode Judgment, Not Boilerplate

Good skills tell Codex:

• What to prioritize
• What to avoid
• What tradeoffs matter
• What "done" means

Bad skills just restate obvious framework syntax or dump long tutorials.

Quality Standard

Every skill in this repo should help Codex produce outputs that are:

• Production-ready
• Secure by default
• Performance-conscious
• Testable and maintainable
• User-centered
• Explicit about failure handling and operational risk

Use world-class-engineering as the baseline when writing engineering skills.

Frontmatter Standard

Use this template:

---
name: skill-name
description: Use when ...
---

Guidelines:

• name must match the directory name exactly.
• Keep the description direct and specific.
• Front-load the main trigger phrase.
• Avoid filler and marketing language.

Reference Strategy

If a skill covers multiple subdomains, split references by topic so each file has a single clear purpose (for example, one file for security gates, one for a schema checklist, and one for a review template). Name each file after the topic it owns, keep it loadable on its own, and link it directly from SKILL.md.

Do not reinvent common templates. The skill-composition-standards skill already ships a reusable template library under its references/ directory, including a threat-model-template.md for security gates, an entity-model-template.md and normalisation-playbook.md for schema work, and a test-plan-template.md for review and verification. Reuse those before creating a new local reference.

Do not bury important files several levels deep. Link them directly from SKILL.md.

Book and Source-File Distillation Rule

When the user provides books, EPUBs, PDFs, course notes, long articles, or other source files while creating or upgrading a skill:

• Treat the source files as temporary inputs. The finished skill must remain useful after those files are deleted, moved, or renamed.
• Do not merely link to the source file path. Distill the practical knowledge into self-contained references/*.md files.
• Preserve operational knowledge: workflows, decision tables, checklists, failure modes, examples, quality gates, and output requirements.
• Keep SKILL.md concise. Put durable depth in directly linked reference files.
• Avoid copying long passages. Summarize, synthesize, and convert book knowledge into reusable execution rules.
• Add a short note in the reference file saying it is self-contained and was prepared from provided source material, so future agents do not depend on the original file.
• If the source material is broad, split the result by practical topic rather than by book chapter.
• Validate that every new reference is linked from SKILL.md with clear conditions for when to load it.

Upgrade Checklist

When improving an existing skill:

• Remove vague or generic advice.
• Add decision rules and release gates.
• Add real failure cases and anti-patterns.
• If book/source files were provided, make the upgraded skill self-contained and do not depend on those files continuing to exist.
• Tighten the activation description.
• Link to other skills only when the dependency is genuinely useful.
• Re-check line counts after editing.

Validation

After creating or updating a skill:

1. Run python -X utf8 skill-writing/scripts/quick_validate.py <skill-dir> (frontmatter, required sections, dual-compat markers, line limits).
2. Run python -X utf8 skill-writing/scripts/contract_gate.py --skill <skill-dir> (Evidence Produced contract from validation-contract). Use --all to scan the whole repo, --bundle <path> to validate a Release Evidence Bundle, and --strict to treat warnings as errors.
3. Fix any frontmatter, structure, or contract issues.
4. Sanity-check the skill against a realistic prompt.
5. Ensure the skill still reads cleanly when loaded on its own.

Anti-Patterns

• Huge SKILL.md files that act like textbooks.
• Trigger descriptions that are too broad to be useful.
• Skills that duplicate existing skills without raising the quality bar.
• Example-heavy files with little operational guidance.
• Instructions that ignore security, performance, testing, or maintainability.

Companion Skills

• Load world-class-engineering when authoring engineering skills.
• Load skill-safety-audit before sharing high-impact or security-sensitive skills.