# How to Add New Features to Arc-Kit: A Complete Slash Command Development Guide

> Learn how to add new features to Arc-Kit by creating command files, templates, and guides. Follow this complete slash command development guide for the tractorjuice/arc-kit repository.

- Repository: [tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit)
- Tags: how-to-guide
- Published: 2026-04-19

---

**To add new features to arc-kit, create a markdown command file in `arckit-claude/commands/`, add any required templates to `arckit-claude/templates/`, write a user guide in `docs/guides/`, and run `python scripts/converter.py` to generate assets for all supported AI platforms.**

Arc-kit is an open-source architecture toolkit that uses markdown-based slash commands to automate enterprise documentation workflows. When you add new features to arc-kit, you extend its plugin ecosystem for Claude, Codex, OpenCode, Gemini, and GitHub Copilot simultaneously. This guide walks through the exact file locations, frontmatter syntax, and conversion pipeline used in the `tractorjuice/arc-kit` repository.

## Understanding the Arc-Kit Command Architecture

Arc-kit’s functionality is driven by **markdown-based commands** that live in the Claude plugin directory (`arckit-claude/commands/`). Each command is a plain markdown file containing YAML frontmatter metadata and a prompt body.

When you add new features to arc-kit, a conversion pipeline automatically generates matching assets for other AI targets. The [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) engine reads the Claude source files and produces compatible formats for:

- **Codex** (`.codex/` and `.agents/skills/`)
- **OpenCode** (`.opencode/`)
- **Gemini** (`arckit-gemini/`)
- **Copilot** (`arckit-copilot/`)

## Step-by-Step Guide to Adding New Features to Arc-Kit

### 1. Create the Command Markdown File

All Claude-Code commands are plain markdown files under `arckit-claude/commands/`. The filename becomes the slash command name (e.g., [`risk-matrix.md`](https://github.com/tractorjuice/arc-kit/blob/main/risk-matrix.md) becomes `/arckit.risk-matrix`).

The file must contain a YAML front-matter block that declares the command name, description, effort level, and any hand-offs.

```markdown
---
description: Create a new <feature> document
effort: low                # optional – overrides session effort

handoffs:
  - command: next-step
    description: Run the next step after this command
---

You are an enterprise architect. Use the provided template 
`{{template}}` to generate a **{{document_type}}** document.

1. Gather any inputs the user supplied.
2. Fill in the template fields.
3. Write the document to `{{output_path}}` using the Write tool.
4. Return a short summary to the user.

```

Save the file as `arckit-claude/commands/<command-name>.md`.

**Key source file**: [`arckit-claude/commands/requirements.md`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-claude/commands/requirements.md) – a full example of a production command.

### 2. Add or Update Document Templates

Most commands render a document from a markdown template located under `.arckit/templates/`. Create a new template file named `<command-name>-template.md` and place it in `arckit-claude/templates/`.

When a project is initialized, the CLI copies these defaults into the user’s `.arckit/templates/` directory.

```markdown

# Document Control

| Field | Value |
|-------|-------|
| Document ID | {{generate_id}} |
| Document Type | {{document_type}} |
| Project | {{project_name}} |
| Classification | {{classification}} |
| Status | DRAFT |
| Version | 1.0 |
| Created Date | {{date}} |
| Owner | {{owner}} |

# {{title}}

## Overview

*Brief description …*

## Details

*…*

```

The command’s prompt can reference the template using `${CLAUDE_PLUGIN_ROOT}/templates/<template-name>.md`.

**Key source file**: [`arckit-claude/templates/requirements-template.md`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-claude/templates/requirements-template.md) – the official requirements template.

### 3. (Optional) Create an Agent for Heavy Research

If the command performs many `WebSearch` / `WebFetch` or long-running MCP calls (≥10 calls), implement the logic in an **agent** to isolate the heavy context.

Create a file `arckit-claude/agents/arckit-<command-name>.md` with the same front-matter schema as a command, but add an `initialPrompt` containing the full research process.

```yaml
---
name: arckit-<command-name>
description: |
  Use this agent when deep market research is needed.
model: inherit
---

You are an autonomous research assistant. Follow this process:

1. Read the user’s brief.
2. Perform up to 20 WebSearch/WebFetch calls to gather sources.
3. Summarise findings.
4. Write a markdown document using the appropriate template.
5. Return only a concise summary.

```

The slash command should be a thin wrapper that launches the agent via the `Task` tool.

**Key source file**: [`arckit-claude/agents/arckit-research.md`](https://github.com/tractorjuice/arc-kit/blob/main/arckit-claude/agents/arckit-research.md) – the standard research agent.

### 4. Write the User Guide

Add a user-facing guide under `docs/guides/` so that the generated project README lists the command with a description.

```markdown

# `/arckit.my-feature`

Create a **My Feature** document.

## Usage

```

/arckit.my-feature <project-name>

```

The command will:

1. Prompt for required fields.  
2. Generate `{{output_path}}` based on the template.  
3. Return a summary.

## Hand-offs

- `next-step` – run after this command to continue the workflow.

```

**Key source file**: [`docs/guides/requirements.md`](https://github.com/tractorjuice/arc-kit/blob/main/docs/guides/requirements.md) – the guide for the built-in requirements command.

### 5. Run the Converter to Generate Multi-AI Assets

All non-Claude formats (Codex, OpenCode, Gemini, Copilot) are generated by [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py).

```bash

# From the repository root

python scripts/converter.py

```

The converter generates the following outputs:

| Target | Output location | Generated content |
|--------|----------------|-------------------|
| **Claude** | `arckit-claude/` | Commands & agents (source of truth) |
| **Codex** | `.codex/` & `.agents/skills/` | Markdown prompts + skill directories |
| **OpenCode** | `.opencode/` | Markdown commands + agents |
| **Gemini** | `arckit-gemini/` | TOML command files |
| **Copilot** | `arckit-copilot/` | [`.prompt.md`](https://github.com/tractorjuice/arc-kit/blob/main/.prompt.md) files |

**Key source file**: [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) – the conversion engine.

### 6. Test the New Feature Across AI Targets

**Claude Code (plugin)**:
1. Open any repo with the ArcKit plugin enabled.
2. Run `/arckit.<command-name>` in the Claude chat.
3. Verify the document is written to the expected location.

**Codex CLI**:

```bash

# Inside an ArcKit-initialised project

$arckit-<command-name>

```

Check that the command resolves to a skill in `~/.agents/skills/`.

**OpenCode CLI**:

```bash
opencode
/arckit.<command-name>

```

Confirm the generated command appears under `.opencode/commands/`.

**Gemini / Copilot**:
Run the corresponding prompt (`/arckit:<command-name>` for Gemini, `/arckit-<command-name>` for Copilot) and verify output.

## Key Files and Directories for Arc-Kit Development

When you add new features to arc-kit, you will interact with these specific paths:

| Path | Role |
|------|------|
| `arckit-claude/commands/*.md` | Source markdown command definitions (Claude plugin) |
| `arckit-claude/templates/*.md` | Document templates used by commands |
| `arckit-claude/agents/*.md` | Heavy-research agents (optional) |
| `docs/guides/*.md` | Human-readable command guides |
| [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) | Generates Codex/OpenCode/Gemini/Copilot assets |
| [`src/arckit_cli/__init__.py`](https://github.com/tractorjuice/arc-kit/blob/main/src/arckit_cli/__init__.py) | CLI entry point that copies templates and runs the converter during `arckit init` |
| `VERSION` / `arckit-claude/VERSION` | Version identifiers for releases |
| [`scripts/bump-version.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/bump-version.sh) | Automates version bump across the repo |
| [`scripts/push-extensions.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/push-extensions.sh) | Deploys generated extensions to their dedicated repos |

## Versioning and Release Management

If you intend to ship the new feature as part of a release:

1. Bump the version in `VERSION` and `arckit-claude/VERSION`.
2. Run `scripts/bump-version.sh <new-version>` to propagate the change.
3. Commit, tag (`git tag -a vX.Y.Z`) and push.
4. Run [`scripts/push-extensions.sh`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/push-extensions.sh) to sync the generated extensions to their separate repos.

## Summary

To successfully add new features to arc-kit:

- Create a command markdown file in `arckit-claude/commands/` with YAML frontmatter defining the description, effort level, and hand-offs.
- Add corresponding templates to `arckit-claude/templates/` for document generation.
- Implement an agent in `arckit-claude/agents/` only if the feature requires heavy web research or MCP calls.
- Document the feature in `docs/guides/` for end-user discoverability.
- Execute `python scripts/converter.py` to generate compatible assets for Codex, OpenCode, Gemini, and Copilot.
- Test the command across all target AI environments before releasing.

## Frequently Asked Questions

### What file format does arc-kit use for slash commands?

Arc-kit uses plain markdown files with YAML frontmatter. The frontmatter defines metadata such as `description`, `effort` level, and `handoffs`, while the markdown body contains the prompt instructions sent to the AI. These files live in `arckit-claude/commands/` and serve as the single source of truth for all other AI targets.

### Do I need to manually create files for Codex, OpenCode, Gemini, and Copilot?

No. The [`scripts/converter.py`](https://github.com/tractorjuice/arc-kit/blob/main/scripts/converter.py) automation handles this for you. When you run the converter, it reads the Claude source files and generates the appropriate formats for each target platform, including TOML files for Gemini and skill directories for Codex. This ensures all AI targets remain synchronized with a single source of truth.

### When should I create an agent instead of a standard command?

Create an agent in `arckit-claude/agents/` when your feature requires heavy web research, multiple MCP tool calls, or more than approximately 10 sequential `WebSearch` or `WebFetch` operations. Agents isolate the heavy context from the main conversation, preventing context window overflow. Standard commands should remain thin wrappers that delegate to agents when intensive processing is required.

### How do I test my new feature before submitting a pull request?

First, run `python scripts/converter.py` to ensure all assets generate without errors. Then test in Claude Code by running `/arckit.<command-name>` in a project with the plugin enabled. For Codex, test with `$arckit-<command-name>` and verify the skill appears in `~/.agents/skills/`. Finally, verify the generated files exist in `.opencode/`, `arckit-gemini/`, and `arckit-copilot/` directories before committing.