aufrank/creating-skills

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.