# For AI agents `foley` ships artifacts for coding agents alongside its code. This page lists them, says where each lives in the repository, and points at the machine-readable copies of this documentation. ## Skills Skills are folders holding a `SKILL.md` (the [Agent Skills](https://agentskills.io) format): a description that tells an agent when to use it and a body with the procedure. Install one into your agent with `gh skill` (any host: `--agent claude-code`, `copilot`, `cursor`, `codex`, `gemini`), or use the copy bundled in the wheel. ### `foley-sound-design` Use when sound-designing a NARRATION with the `foley` package — choosing sound effects for narrated/voiced text and weaving them under the voice. Triggers on: “add sound effects to this narration”, “score this passage”, “sound-design this audiobook/podcast/video script”, “find a sound for this line”, “weave SFX into the voiceover”, “make a sound-design timeline”, or any task that pairs narration text (or a transcript) with choosing + placing sounds. Covers the find→plan→weave loop, the one-call `foley.score()`, the MCP tool surface, and the taste heuristics (restraint, layering, ducking, licensing). ```bash gh skill install thorwhalen/foley foley-sound-design --agent claude-code ``` Source: [`foley/data/skills/foley-sound-design`](https://github.com/thorwhalen/foley/tree/HEAD/foley/data/skills/foley-sound-design) (bundled with the pip package). ### `foley-dev-add-source` Use when adding a new sound SOURCE to foley — either a retrieve adapter (a sound-library/API such as Freesound, BBC Sound Effects, Epidemic, Storyblocks, Pond5) or a generate adapter (a text-to-SFX model/API such as Stable Audio Open, ElevenLabs Sound Effects, AudioGen). Covers the SOURCE_CONFIG plugin pattern (mirroring arioso’s per-platform config), the SourceAdapter protocol, unified query/generation vocabulary → native-param translation, lazy optional-deps, and the mandatory per-source license policy (commercial_ok / redistribute_standalone_ok / cache_bytes_ok / ai_training_ok). Triggers on adding a source, adding an adapter, wiring a new SFX API or generator into foley. ```bash gh skill install thorwhalen/foley foley-dev-add-source --agent claude-code ``` Source: [`skills/foley-dev-add-source`](https://github.com/thorwhalen/foley/tree/HEAD/skills/foley-dev-add-source). ### `foley-dev-implement` Use when implementing (or planning to implement) any foley epic subtask — building the SOURCE / INDEX / SELECT / WEAVE stages or the cross-cutting layers of the foley SFX façade. Covers the build loop, the module layout, the canonical data models (SoundRecord, LicenseRecord, Candidate, SoundDesignTimeline), the non-negotiable invariants (license SSOT + fail-closed gate, cache_bytes_ok vs redistribute_standalone_ok, the eval PR gate, AI disclosure), the façade discipline (mirror arioso/accompy), and the branch→PR git flow. Triggers on foley implementation, foley subtask, foley adapter/index/agent/weave work, foley base.py / data models. ```bash gh skill install thorwhalen/foley foley-dev-implement --agent claude-code ``` Source: [`skills/foley-dev-implement`](https://github.com/thorwhalen/foley/tree/HEAD/skills/foley-dev-implement). The bundled skills are also on disk after `pip install foley`, under the package’s `data/skills/` directory; link them into an agent without network access with `skill link-skills `. ## Instruction files Files agents read before working in this repository. - [`.claude/CLAUDE.md`](https://github.com/thorwhalen/foley/tree/HEAD/.claude/CLAUDE.md): read by Claude Code ## Machine-readable documentation This site publishes the same documentation in forms that fit an agent’s context window: - [`llms.txt`](https://thorwhalen.github.io/foley/llms.txt): an index of every page with a one-line description ([llms.txt](https://llmstxt.org) format) - [`foley.md`](https://thorwhalen.github.io/foley/foley.md): the whole documentation as one Markdown file - `.html.md`: a rendered Markdown twin of every page, advertised from each page’s `` with `` - [`objects.inv`](https://thorwhalen.github.io/foley/objects.inv): the Sphinx inventory: a symbol-to-URL index (`sphobjinv convert plain objects.inv -`)