Ox-skills is an Org exporter backend that exports Org files to SKILL.md files with YAML frontmatter.

Write your AI coding assistant skills in Org-mode. Keep your prompt engineering in the same place as your notes, export with a single command, and never hand-edit YAML again.

Set SKILL_BASE_DIR to the directory where skills should be written, add SKILL_* keywords, and write the skill body:

#+SKILL_NAME: review
#+SKILL_DESCRIPTION: Review code changes in the current branch
#+SKILL_ALLOWED_TOOLS: Bash Read
#+SKILL_USER_INVOCABLE: true
#+SKILL_BASE_DIR: ~/.claude/skills

* Instructions

Focus on correctness, not style. Check for edge cases.

#+begin_src sh :inject yes
git diff HEAD
#+end_src

Export with the Org export dispatcher (M-x org-export-dispatch or C-c C-e). The Skills backend appears under the s key:

[s] Export to SKILL.md
    [s] File to SKILL.md
    [S] File to a temporary buffer
    [w] Subtree or File to SKILL.md
    [a] All subtrees (or File) to SKILL.md

The skill is written to {SKILL_BASE_DIR}/{SKILL_NAME}/SKILL.md — in this example, ~/.claude/skills/review/SKILL.md.

Source blocks with :inject yes become ```! blocks, executed at invocation time to inject fresh context into the skill:

#+begin_src sh :inject yes
git diff HEAD
#+end_src

Exports as:

```!
git diff HEAD
```

Regular source blocks export as standard fenced code blocks.

Keep all your skills in one Org file. Give each heading an EXPORT_SKILL_NAME property, set a shared SKILL_BASE_DIR, then run M-x ox-skills-export-wim-to-md (or C-c C-e s w) to export all at once:

#+SKILL_BASE_DIR: ~/.claude/skills

* Review skill
:PROPERTIES:
:EXPORT_SKILL_NAME: review
:EXPORT_SKILL_DESCRIPTION: Review code changes
:EXPORT_SKILL_ALLOWED_TOOLS: Bash Read
:END:

...

* Deploy skill
:PROPERTIES:
:EXPORT_SKILL_NAME: deploy
:EXPORT_SKILL_DESCRIPTION: Deploy to production
:END:

...

This writes ~/.claude/skills/review/SKILL.md and ~/.claude/skills/deploy/SKILL.md.

Set SKILL_BASE_DIR to wherever your tool expects skills — ox-skills writes directly into that directory, no subdirectory is appended automatically.

Organise skills into subdirectories by declaring section headings with EXPORT_SKILL_SUBDIR. When WIM export runs on a skill below a section, each ancestor’s EXPORT_SKILL_SUBDIR value becomes a path segment:

#+SKILL_BASE_DIR: ~/.claude/skills

* Engineering
:PROPERTIES:
:EXPORT_SKILL_SUBDIR: engineering
:END:

** Tools
:PROPERTIES:
:EXPORT_SKILL_SUBDIR: tools
:END:

*** Code Review
:PROPERTIES:
:EXPORT_SKILL_NAME: code-review
:EXPORT_SKILL_DESCRIPTION: Review code changes
:END:

...

This produces:

~/.claude/skills/
└── engineering/
    └── tools/
        └── code-review/
            └── SKILL.md

In general, ~/.claude/skills/engineering/tools/code-review/SKILL.md.

Section headings without EXPORT_SKILL_NAME are not exported themselves — they only contribute their EXPORT_SKILL_SUBDIR segment to the paths of any skills nested beneath them. Sections can be nested to any depth.

This is purely an organisational convenience: harnesses like Claude Code and OpenCode discover skills by scanning all subdirectories under the skills root, so a skill at engineering/tools/code-review/SKILL.md is found just as reliably as one at code-review/SKILL.md.

List fields are space-separated; quote multi-word items. Boolean fields accept true=/=yes or false=/=no. Subtree exports use EXPORT_SKILL_* property drawer syntax.

(use-package ox-skills
  :straight (:host github :repo "gicrisf/ox-skills"))

(use-package ox-skills
  :vc (:url "https://github.com/gicrisf/ox-skills"
            :rev :newest
            :branch "main"))

In ~/.config/doom/packages.el:

(package! ox-skills :recipe (:host github :repo "gicrisf/ox-skills"))

In ~/.config/doom/config.el:

(use-package! ox-skills)

Then run doom sync.

For a real-world example, check out gicrisf/skills, a collection of AI agent skills exported from Org-mode with ox-skills. It demonstrates:

• A SKILLS.org with multiple skills using EXPORT_SKILL_* properties
• The WIM export workflow (M-x ox-skills-export-wim-to-md)
• How to easily symlink skills into ~/.claude/skills, ~/.opencode/skills, etc.
• A org-skill-maker meta-skill to bootstrap new skills interactively

If you’re just starting with org skills, use it as a reference or starting point.

Did you find this package useful? Buy me a coffee!

Open sourced under the GPL-3.0 license.