# How to Contribute a New Task Guide Under agents/skills/ in Omarchy

> Learn to contribute a new task guide to Omarchy in agents/skills/. Follow our easy steps for Markdown, H1 headings, structure, and AGENTS.md registration.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-09

---

**To contribute a new task guide to Omarchy, create a Markdown file in `agents/skills/` with a kebab-case filename, follow the standard H1 heading and section structure, and register it in [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) before running the shell test suite.**

Omarchy stores procedural documentation as flat Markdown files inside the `agents/skills/` directory. Each guide follows conventions established by existing files like [`visual-verification.md`](https://github.com/omacom/omarchy/blob/main/visual-verification.md) and [`command-metadata.md`](https://github.com/omacom/omarchy/blob/main/command-metadata.md), ensuring the CLI scanner and documentation index can parse your contribution correctly.

## Create the Task Guide File

### Naming Conventions

Place your new guide directly under `agents/skills/` using a descriptive, kebab-case filename. The filename becomes the permanent URL path for the guide.

- **Good**: [`my-feature.md`](https://github.com/omacom/omarchy/blob/main/my-feature.md), [`secure-deployment.md`](https://github.com/omacom/omarchy/blob/main/secure-deployment.md)
- **Bad**: [`MyFeature.md`](https://github.com/omacom/omarchy/blob/main/MyFeature.md), [`my_feature.md`](https://github.com/omacom/omarchy/blob/main/my_feature.md), [`guide.md`](https://github.com/omacom/omarchy/blob/main/guide.md)

### File Structure Header

Start the file with a level-1 heading that matches the title of your task. The `bin/omarchy` CLI scanner inspects the first 80 lines of each file for command metadata, so keep the header and introduction concise.

```markdown

# My Feature

Read this before using the new feature.

```

This mirrors the style found in [`agents/skills/visual-verification.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/visual-verification.md), which begins with a heading followed by a brief imperative instruction.

## Structure the Content Sections

Follow the standard flat layout used across the repository. Typical guides include five core sections:

1. **Overview** — High-level description of what the task accomplishes.
2. **Prerequisites** — Required tools, permissions, or environment variables.
3. **Step-by-step instructions** — Numbered commands or actions.
4. **Examples** — Fenced code blocks showing common usage.
5. **Verification** — How to confirm the task succeeded.

### Required Sections

Keep paragraphs short and scannable. The introduction should explain the purpose in one to two sentences, similar to the "Read this before finishing any change" paragraph in [`visual-verification.md`](https://github.com/omacom/omarchy/blob/main/visual-verification.md).

When referencing existing conventions—such as CLI flag definitions—add an inline link to the relevant guide:

```markdown
See [`agents/skills/command-metadata.md`](agents/skills/command-metadata.md) for flag definitions.

```

### Code Examples and Verification

Use fenced Bash blocks for all commands. Include a verification step that shows the expected output, referencing other guides when appropriate.

```markdown

## Steps

1. Activate the mode:
   ```bash
   omarchy enable-awesome
   ```

2. Verify the status:
   ```bash
   omarchy status | grep awesome
   ```

## Verification

The command should output `awesome: enabled`. If not, see the troubleshooting section in `agents/skills/visual-verification.md`.

```

## Update the Documentation Index

The master list of task guides lives in [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) at the repository root. Add a bullet that links to your new file using the existing pattern:

```markdown
- [`agents/skills/my-feature.md`](agents/skills/my-feature.md) – Short description of the guide

```

Without this entry, your guide will not appear in the documentation navigation even though the file exists in `agents/skills/`.

## Validate Your Contribution

Before submitting, run the repository's shell-level test suite to ensure no linting or formatting errors were introduced:

```bash
./test/shell

```

The CI pipeline automatically executes these tests on every pull request. If the CLI scanner detects malformed metadata in the first 80 lines of your file, the tests will fail.

Once tests pass, fork the repository, push your branch, and open a pull request. The maintainers will review for adherence to the flat layout conventions and merge once CI passes.

## Summary

- Create a kebab-case Markdown file under `agents/skills/` with a descriptive name like [`my-feature.md`](https://github.com/omacom/omarchy/blob/main/my-feature.md).
- Start with an H1 heading and concise introduction within the first 80 lines to satisfy the CLI scanner.
- Include Overview, Prerequisites, Steps, Examples, and Verification sections using fenced Bash blocks.
- Reference related guides like [`command-metadata.md`](https://github.com/omacom/omarchy/blob/main/command-metadata.md) when discussing CLI conventions.
- Register the guide in [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) using the standard bullet format.
- Run `./test/shell` locally to verify formatting before submitting your pull request.

## Frequently Asked Questions

### What filename format should I use for a new task guide?

Use kebab-case (hyphen-separated lowercase) filenames such as [`secure-deployment.md`](https://github.com/omacom/omarchy/blob/main/secure-deployment.md). The filename becomes the permanent link, and the repository conventions reject camelCase or snake_case variants.

### How long can the introduction of my task guide be?

Keep the header and introduction within the first 80 lines. The `bin/omarchy` scanner only inspects this range for command metadata, so place critical information early and avoid heavy tables or long prose up front.

### Do I need to update any index files when adding a guide?

Yes. You must add an entry to [`AGENTS.md`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) at the repository root. Without this bullet link, the guide exists in `agents/skills/` but will not appear in the documentation navigation or task indexes.

### How do I verify my task guide meets repository standards?

Run the shell test suite with `./test/shell` to check for linting errors and metadata format issues. The CI pipeline enforces these checks automatically on every pull request.