import { AGENT_SKILL_MD, AGENT_SKILL_RAW_HREF } from "@/features/agent-skill/skill-md";

export const metadata = {
  title: "Agent Skill for AI",
  description:
    "A ready-to-use Anthropic Agent Skill (SKILL.md) that teaches Claude, Cursor, and other AI agents how to call the FaithTranscripts API to clean transcripts, fix biblical names, and link scripture references.",
  alternates: { canonical: "/docs/api/agent-skill" },
};

<div className="mb-2 font-medium text-gold text-xs uppercase tracking-widest">
  For AI Agents
</div>

# Agent Skill: FaithTranscripts API

<SkillActions href={AGENT_SKILL_RAW_HREF} filename="SKILL.md" />

This page publishes a complete **[Agent Skill](https://www.anthropic.com/news/agent-skills)**
that teaches Claude (and any compatible agent — Claude Code, Cursor, Claude
Cowork, ChatGPT, Codex, etc.) how to correctly call the FaithTranscripts
API to clean transcripts, correct biblical names and places, and link scripture
references in sermons, podcasts, and video subtitles.

Drop the `SKILL.md` below into your agent's skills directory and your assistant
will know when and how to use the FaithTranscripts API without you re-explaining
the API surface every time.

<Callout variant="tip">
  **Why a skill and not just a prompt?** Agent Skills use _progressive
  disclosure_: the model sees a short `name` and `description` up front, and
  only loads the full instructions when the task matches. That keeps context
  small while still giving the agent an authoritative, versioned reference.
</Callout>

## Install

Copy the file below into the location your agent reads skills from:

| Agent             | Location                                             |
| ----------------- | ---------------------------------------------------- |
| Claude Code       | `~/.claude/skills/faith-transcripts/SKILL.md`        |
| Cursor (per-user) | `~/.cursor/skills-cursor/faith-transcripts/SKILL.md` |
| Cursor (per-repo) | `.cursor/skills/faith-transcripts/SKILL.md`          |
| Claude Agent SDK  | Pass the directory to the skill loader at startup.   |

Then create an API key in [Settings → API Keys](/settings/api-keys) and expose
it to the agent as the `FAITH_TRANSCRIPTS_API_KEY` environment variable.

## The skill

Paste this entire file, verbatim, as `SKILL.md` — or use the buttons below to
copy it to your clipboard or download it directly.

<SkillActions href={AGENT_SKILL_RAW_HREF} filename="SKILL.md" />

<CodeBlock language="markdown" title="SKILL.md">{AGENT_SKILL_MD}</CodeBlock>

## Verify it works

Once the skill is installed, a smoke-test prompt like the following should
cause the agent to pick up the skill and call the API:

> "Clean this sermon transcript for me: _Today we read from Jon 3 about the
> city of Ninevah._"

The agent should recognize the faith content, load the skill, call
`POST /api/v1/transcripts` with `source_type: "paste"`, and return the
corrected text (`Jonah 3`, `Nineveh`) along with a change summary.

## Keep the skill fresh

The `description` field is the most important line in the file — it's what the
model uses to decide whether to load the skill. When the API gains a new
capability, update both the description (so the model knows to reach for the
skill) and the body (so it knows how to call the new endpoint). Minor
endpoint-reference drift is covered by the full machine-readable index at
[`/llms-full.txt`](/llms-full.txt) — agents that need the absolute latest
surface area can fetch that directly.

## Related

- [Overview](/docs/api) — what the API does and why.
- [Quickstart](/docs/api/quickstart) — a hand-run five-minute integration.
- [Endpoint reference](/docs/api/reference) — canonical endpoint list.
- [Zapier integration](/integrations/zapier) and [n8n integration](/integrations/n8n) — no-code alternatives if you'd rather not run an agent at all.