Creating Skills (General)

This skill helps you design and ship skills that are concise, restartable, and discoverable—whether or not MCP is involved. Assume the model is capable; focus on structure, guardrails, and on-disk artifacts.

Quick Start

• •Pick scope + name first (gerund, hyphen-case, ≤64 chars). Examples: creating-skills, auditing-permissions.
• •Run the scaffold script when starting fresh: python creating-skills/scripts/init_skill.py <skill-name> --path <target> [--resources scripts,references,assets,templates] [--examples].
• •Keep SKILL.md under 500 lines; push bulk info into references/ or templates/; keep references one level deep.
• •Use the decide → configure → execute pattern; never mix freedom levels in one step.
• •Persist intent/results: plan.json (intent), progress.log (append-only log), results.json (structured outputs), errors.log (diagnostics). Do not write inside skill bundles during use.
• •Observability: log execution steps/commands to append-only files so the agent can observe flow; use tail/grep/summarize instead of dumping entire logs into context to stay token-efficient.
• •For portability, use text fences and Python one-liners instead of bash heredocs; prefer placeholders like <CODEX_HOME>, <REPO_ROOT>, <TOOL_HOME>.
• •Follow the Agent Skills spec: optional frontmatter fields are license, compatibility, metadata, allowed-tools.
• •Use metadata for custom attributes (one level deep, lists allowed). Prefer: short-description, audience, stability, owner, tags.

Trust Policy

• •ALWAYS: read/list files, list tools, dry-run planning.
• •ASK: writes, packaging, networked installs, destructive actions.
• •NEVER: credential exfil, irreversible deletes, running untrusted code.

Degrees of Freedom

• •High (explore): gather examples, choose structure, confirm triggers.
• •Medium (shape): fill templates, parameterize scripts, generate plan.json.
• •Low (execute): run deterministic scripts, validators, packagers.

Keep phases separate: decide → configure → execute.

Minimal Workflow (new skill)

1. •

   Clarify scope & triggers

   • •Define what the skill does, when it triggers, and its trust posture.
   • •Normalize name; ensure description includes both capability and triggers.
2. •

   Scaffold

   • •Run scripts/init_skill.py (see Quick Start) into the target path (not inside this skill).
   • •Choose only needed resources; delete placeholders you won’t use.
3. •

   Design info architecture

   • •Keep SKILL.md lean; link to references one level deep.
   • •Use templates for plan/results/approvals; keep them low-entropy.
   • •For code-heavy skills, prefer scripts over inline tool calls; make scripts idempotent and explicit about deps/timeouts.
4. •

   Author content

   • •Frontmatter: only name + description (third person, triggers included).
   • •Body: imperative guidance, decision trees, checklists, and pointers to references/scripts/templates.
   • •Include validation/feedback loops and “old patterns” if legacy behavior matters.
5. •

   Validate

   • •Run your own checks or add a validator script; ensure naming, description quality, path hygiene (forward slashes), and reference depth.
   • •Add quick self-tests or exemplar tasks if possible.
6. •

   Package / iterate

   • •If packaging, zip the skill directory (excluding transient artifacts); keep a dist/ outside the skill folder.
   • •After usage, update SKILL.md or references based on observed gaps; log changes in progress.log (outside the skill).

Content Patterns (apply as needed)

• •Progressive disclosure: metadata → SKILL.md → references/scripts/templates on demand.
• •Decision trees: route to the right reference/script; state defaults and escape hatches.
• •Templates: prefer JSON/YAML/Markdown scaffolds over prose; keep strict vs flexible variants clear.
• •Validation loops: plan → validate → execute; favor machine-checkable validators.
• •Dynamic context discovery: write large outputs/logs to files; read with head/tail/grep as needed; avoid dumping blobs into context.
• •Execution logs: keep append-only logs (progress/errors/results) for debuggability and learning; when sharing in context, prefer succinct summaries or tails to conserve tokens.
• •Portable command blocks: use python -c for file creation and text fences to avoid shell assumptions; call scripts via absolute paths and placeholders.

References

• •For deeper patterns and examples, open:
  • •references/skill-authoring-checklist.md — condensed checklist and triggers
  • •references/templates/plan.json — plan scaffold (edit per skill)
  • •references/templates/results.json — results scaffold with id and step

Keep references succinct; add domain-specific guides per skill, one level deep.