writing-for-agents

Files (4)

• SKILL-MECHANICS.md
• SKILL.md
• openai.yaml · agents/
• principles.md

SKILL.md (first lines)

# Write instructions for agents

State the task, conditions that change decisions, essential constraints, and an observable completion condition. Preserve the user's goal and existing authorization; a reusable workflow does not authorize extra work.

Keep discovery descriptions short and specific. Read existing instructions and relevant executable configuration before adding a rule. Put each fact in its narrowest durable home and link it from the place that needs it.

Keep shared workflow in the entrypoint. Move mode-specific examples, schemas, and procedures behind links that say when to read them. A small self-contained skill does not need extra files. Use detailed sequences for real protocol or safety invariants; let routine implementation choices follow the task evidence.

For frontmatter or discovery changes, read [SKILL-MECHANICS.md](SKILL-MECHANICS.md). For a difficult instruction-design problem, consult [principles.md](principles.md) on context pointers, disclosure, completion criteria, and pruning. Ordinary wording edits need only the relevant existing context.

Validate the actual artifact: references resolve, supported metadata parses, helpers run when changed, and the workflow completes a representative task without adding unauthorized actions. Use observed failures to justify stronger rules; do not add generic instructions merely because they might help.

From jamesdebatty/skills, MIT.

More from jamesdebatty/skills