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

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 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 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.

---
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 – 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.

# 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 – 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.

---
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 – 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.

# `/arckit.my-feature`

Create a **My Feature** document.

## Usage

/arckit.my-feature

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 – 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.

# 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 files

Key source file: 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:

# Inside an ArcKit-initialised project

$arckit-<command-name>

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

OpenCode CLI:

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	Generates Codex/OpenCode/Gemini/Copilot assets
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	Automates version bump across the repo
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 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 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.

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