How to use the ARA Compiler agent skill (ara-compiler)

What is an agent skill and what does ara-compiler do?

An agent skill is a folder containing a SKILL.md file and supporting reference files. When installed, the agent can load these instructions and follow them for matching tasks. The ara-compiler skill is written for agents like Claude Code that can read and write files and run shell commands.

Once installed, the agent can take a research input and reorganize it into an ARA. The artifact covers a cognitive layer (claims, concepts, heuristics), a physical layer (configs, code stubs), an exploration graph, and grounded evidence pointers. The skill also gives step-by-step instructions for reading sources, separating evidence from interpretation, and validating the output.

• Inputs: PDF papers, GitHub repositories, experiment logs, code directories, raw notes
• Outputs: a folder of structured files covering claims, concepts, methods, configs, code stubs, an exploration graph and evidence pointers
• Validation: the skill directs the agent to run a Seal Level 1 check and fix failures

Install the ara-compiler skill

Download the ZIP from this page and unzip it. Then place the skill folder in one of these locations: ~/.claude/skills/ for personal use across projects, or .claude/skills/ inside a specific project. You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Requirements before you start

The skill needs an agent that can read and write files and run shell commands. The source lists these tools: Read, Write, Edit, Bash, Glob and Grep. Claude Code is the agent named in the source. A PaperBench rubric file is optional and only needed if you use the --rubric option.

• Agent with file read/write and shell access (Read, Write, Edit, Bash, Glob, Grep)
• Optional: a PaperBench rubric file for the --rubric option
• The skill runs scripts and uses the network

Trigger the skill with natural requests

You do not need a special command to use the skill. Describe the task in plain language. The skill's description covers requests about ingesting a paper or codebase into a structured, machine-executable knowledge package, building an ARA from scratch, or converting research outputs into a falsifiable, agent-traversable form.

The skill's instructions accept arguments. A file or directory path is read, a URL is fetched or cloned, --output <dir> sets where the ARA is written (default ./ara-output/), and --rubric <path> adds a PaperBench rubric for coverage mapping.

• "Turn this PDF into an Agent-Native Research Artifact."
• "Compile this GitHub repository into an ARA with claims and an exploration graph."
• "Build an ARA from these experiment logs and my raw notes, output to ./my-ara/."
• "Convert this codebase into a falsifiable, agent-traversable form."

What the output folder contains

The schema reference lists the main folders: logic/ (problem, claims, concepts, experiments, related work, and a solution/ subfolder with architecture, algorithm, constraints and heuristics), src/ (configs and execution stubs, plus environment.md), trace/ (exploration_tree.yaml), and evidence/ (with a README.md). A root PAPER.md file holds the manifest and layer index.

The validation checklist requires the root manifest to start with YAML frontmatter containing the keys title, authors and year. Expect many files: the process is long by design.

• PAPER.md: root manifest and layer index
• logic/: problem, claims, concepts, experiments, related_work, solution/
• src/: configs/training.md, configs/model.md, execution/, environment.md
• trace/exploration_tree.yaml and evidence/README.md

Safety notes: scripts and network access

The skill runs scripts and uses the network. The agent reads and writes content locally and may fetch URLs or clone repositories. Only give it sources you have the rights to process. Do not use it on material containing confidential data.

Review what the agent plans to run and fetch, especially when it operates on a repository you did not write.

• Do not process sources you lack the rights to use
• Avoid confidential data, since content is read and written locally and URLs may be fetched
• Check shell commands and network actions the agent proposes

Tips for better results

Give the agent more than one source where possible. The skill's approach is to cross-reference a PDF's narrative and claims with code, experiment logs and notes. Tell the agent where to write output if the default ./ara-output/ is not what you want. If the input is incomplete, expect the agent to ask questions and to mark gaps as not available from the provided input.

• Combine a paper with its repository and logs for better coverage
• Specify --output when you need a fixed location
• Answer the agent's clarifying questions instead of letting it guess
• Ask for the validation step to be run and reported