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

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 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 and 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, secure-deployment.md
• Bad: MyFeature.md, my_feature.md, 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.

# My Feature

Read this before using the new feature.

This mirrors the style found in 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.

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

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.

## Steps

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

2. Verify the status:

   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:

./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.
• 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 when discussing CLI conventions.
• Register the guide in 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. 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}