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

gh skill install thorwhalen/foley foley-sound-design --agent claude-code

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

gh skill install thorwhalen/foley foley-dev-add-source --agent claude-code

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

gh skill install thorwhalen/foley foley-dev-implement --agent claude-code

Source: 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 <that directory>.

Instruction files#

Files agents read before working in this repository.

Machine-readable documentation#

This site publishes the same documentation in forms that fit an agent’s context window:

  • llms.txt: an index of every page with a one-line description (llms.txt format)

  • foley.md: the whole documentation as one Markdown file

  • <page>.html.md: a rendered Markdown twin of every page, advertised from each page’s <head> with <link rel="alternate" type="text/markdown">

  • objects.inv: the Sphinx inventory: a symbol-to-URL index (sphobjinv convert plain objects.inv -)