name: agents-md-to-skills
description: Convert AGENTS.md (or similar agent instruction docs) into reusable Codex skills. Use when asked to extract, split, or refactor AGENTS.md guidance into skill folders, or to create skills that replace sections of an AGENTS.md file.

AGENTS.md to Skills

Turn long or mixed-purpose AGENTS.md guidance into focused, reusable skills that Codex can trigger automatically.

Workflow

1. Locate the source instructions
2. Find the AGENTS.md (or equivalent) file in the repo.

3. Ask which sections to convert if it is unclear or if the file is long.

4. Identify skill candidates

5. Group content that describes a repeatable workflow, tool usage pattern, or domain-specific knowledge.
6. Keep global constraints (security, testing, coding style) in AGENTS.md unless they are truly task-specific.

7. Prefer small, single-responsibility skills.

8. Propose a skill map

9. For each candidate, propose a hyphen-case skill name and a one-line purpose.

10. Merge candidates only if they share the same trigger and steps.

11. Create each skill folder

12. Create .codex/skills/<skill-name>/ in the target repo scope unless the user specifies another location.

13. Add SKILL.md with valid frontmatter (name + description only).

14. Write triggers and instructions

15. In description, include both what the skill does and when to use it (trigger phrases or contexts).
16. In the body, write imperative, step-by-step guidance.
17. Keep SKILL.md lean; move large reference material into references/ and link from SKILL.md.

18. Avoid extra docs inside the skill (no README, changelog, or setup guides).

19. Update AGENTS.md

20. Replace converted sections with short pointers to the skill (e.g., “Use $skill-name for ”).

21. Keep only repository-wide rules and minimal navigation.

22. Validate

23. Ensure name matches the folder and uses lowercase letters, numbers, and hyphens only.
24. Keep description under 1024 characters and single-line.
25. If available, run skills-ref validate on the new skill folder(s).

Heuristics for what to extract

Extract into a skill when the section:
- Describes a multi-step process or checklist.
- Documents a tool workflow, command sequence, or API usage.
- Encodes team-specific conventions for a repeatable task.
- Is large enough to distract from global, repo-wide rules.

Keep in AGENTS.md when the section:
- Defines global policies (security, testing, style).
- Applies to every task regardless of type.
- Is a short reminder that does not justify a new skill.

SKILL.md template

---
name: <skill-name>
description: <what it does + when to use it>
---

<imperative instructions>

Output expectations

• New skill directories with valid SKILL.md files.
• AGENTS.md updated to reference the skills.
• A brief summary of changes and any follow-up questions.