> For the complete documentation index, see [llms.txt](https://developers.raycast.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.raycast.com/information/file-structure.md). # File Structure Understand the file structure of an extension. An extension consists of at least an entry point file (e.g. `src/index.ts`) and a `package.json` manifest file. We add a few more support files when scaffolding an extension to streamline development with modern JavaScript tooling. An extension's directory structure can look like this, including optional files for AI features, setup help, and Store screenshots: ```bash extension ├── .prettierrc ├── ai.json ├── assets │ └── icon.png ├── eslint.config.js ├── help.md ├── metadata │ └── screenshot.png ├── node_modules ├── package-lock.json ├── package.json ├── README.md ├── skills │ └── triage-inbox │ ├── SKILL.md │ └── references ├── src │ ├── command.tsx │ └── tools │ └── tool.ts └── tsconfig.json ``` The directory contains all source files, assets, and a few support files. Let's go over each of them: ## Manifest **package.json** is the most important file in your extension. It defines the extension's metadata, including its title, commands, tools, preferences, and dependencies. See the [manifest reference](/information/manifest.md) for all supported properties. ## Sources Put all your source files into the `src` folder. We recommend using TypeScript as a programming language. Our API is fully typed, which helps you catch errors at compile time rather than runtime. `ts`, `tsx`, `js` and `jsx` are supported as file extensions. As a rule of thumb, use `tsx` or `jsx` for commands with a UI. An extension consists of at least an entry point file (e.g. `src/command.ts`) per command and a `package.json` manifest file holding metadata about the extension, its commands, tools, and skills. The format of the manifest file is very similar to [that of npm packages](https://docs.npmjs.com/cli/v7/configuring-npm/package-json). In addition to some of the standard properties, there are some [additional properties](/information/manifest.md), in particular, the `commands` properties which describes the entry points exposed by the extension. Each command has a property `name` that maps to its main entry point file in the `src` folder. For example, a command with the name `create` in the `package.json` file, maps to the file `src/create{.ts,.tsx,.js,.jsx}`. ### Tools Put tool entry points in `src/tools`. Tools expose functionality that Raycast AI can call, such as searching data or creating an item. Declare each tool in the `tools` array in `package.json`; its `name` maps to a `.ts` or `.tsx` file in this folder. For example, a tool named `search` maps to `src/tools/search.ts`. See [Create an AI Extension](/ai/create-an-ai-extension.md) for a walkthrough. ## Skills Extensions can bundle [Agent Skills](https://agentskills.io/specification) in `skills`. Each skill uses the standard directory format: ```bash skills//SKILL.md ``` `SKILL.md` must start with YAML frontmatter containing a lowercase, hyphenated `name` that matches its directory and a non-empty `description`. The skill directory can also contain scripts, references, assets, and other files referenced by the skill. Every skill must also be declared in `ai.skills` in the extension’s `package.json`, or in the top-level `skills` array of an AI configuration file. The declaration's `name` identifies the matching directory, while `title` provides the human-readable label shown in Raycast. Raycast reads the skill’s description from its `SKILL.md` frontmatter. An optional `icon` overrides the extension icon for skill mentions.. ```json { "ai": { "skills": [ { "name": "triage-inbox", "title": "Triage Inbox" } ] } } ``` For example, the same declaration can live in `ai.json` instead: ```json { "skills": [ { "name": "triage-inbox", "title": "Triage Inbox" } ] } ``` The CLI also supports `ai.json5`, `ai.yaml`, and `ai.yml`. Properties from the AI file override matching properties in `package.json`'s `ai` object; a file's `skills` array replaces the manifest's array. The merged configuration is validated and included in the built manifest, including for extensions without tools. Raycast catalogs declared skills from enabled extensions so users and AI agents can discover them. This does not load their instructions. Mentioning an extension activates its tools but does not load its skills. Mentioning a skill, or loading it through AI routing, loads only that skill and makes its owning extension's tools available for the task. This lets the user select a workflow while Raycast resolves the tools it depends on. ## Assets The optional `assets` folder can contain icons that will be packaged into the extension archive. All bundled assets can be referenced at runtime. Additionally, icons can be used in the `package.json` as extension or command icons. ## Help The optional **help.md** file contains Markdown instructions for configuring required preferences, such as obtaining an API key. Place it next to `package.json`. Raycast bundles it automatically and displays its contents beside the setup form when required preferences are missing. See [Help for Required Preferences](/api-reference/preferences.md#help-for-required-preferences) for an example. ## AI Configuration The optional **ai.yaml** file contains AI configuration, including `skills`, additional `instructions`, and `evals` to test your AI extension. Place it next to `package.json` to keep this configuration separate from the manifest. You can also use `ai.json5`, `ai.yaml`, or `ai.yml`; choose one format for your extension. See [AI File](/ai/learn-core-concepts-of-ai-extensions.md#ai-file) and [Evals](/ai/evals.md). ## Metadata The optional `metadata` folder contains PNG screenshots for your extension's Store listing. These are uploaded when publishing. Put images needed at runtime in `assets`, and images linked from your README in a top-level `media` folder. See [Adding Screenshots](/basics/prepare-an-extension-for-store.md#adding-screenshots) for capture instructions and image requirements. ## Support files The directory contains a few more files that setup common JavaScript tooling: * **eslint.config.js** describes rules for [ESLint](https://eslint.org), which you can run with `npm run lint`. It has recommendations for code style and best practices. Usually, you don't have to edit this file. * **.prettierrc** contains default rules for [Prettier](https://prettier.io) to format your code. We recommend to setup the [VS Code extension](https://prettier.io/docs/en/editors.html#visual-studio-code) to keep your code pretty automatically. * **node\_modules** contains all installed dependencies. You shouldn't make any manual changes to this folder. * **package-lock.json** is a file generated by npm to install your dependencies. You shouldn't make any manual changes to this file. * **tsconfig.json** configures your project to use TypeScript. Most likely, you don't have to edit this file. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.raycast.com/information/file-structure.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.