@ai-outfitter/outfitter 0.9.0 → 0.10.0

package/dist/skills/SkillResolution.js

@@ -0,0 +1,217 @@
+// Resolves selected skill IDs, validates references, and materializes generated skills.
+import { copyFileSync, cpSync, existsSync, mkdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, sep } from 'node:path';
+import { isSkillDocumentIssue, isValidSkillId, readSkillDocument, skillMaterializationSections, } from './SkillDocument.js';
+export const resolveSkillEntries = (input) => {
+    const sources = [];
+    const diagnostics = [];
+    for (const entryInput of input.entries) {
+        const outcome = resolveSkillEntry(input, entryInput);
+        sources.push(...outcome.sources);
+        diagnostics.push(...outcome.diagnostics);
+    }
+    return { sources, diagnostics };
+};
+const resolveSkillEntry = (input, entryInput) => {
+    const { entry, profileReferenceRoot } = entryInput;
+    const selection = typeof entry === 'string' ? { id: entry } : entry;
+    const catalogEntry = input.catalog.entries.get(selection.id);
+    if (catalogEntry === undefined) {
+        return resolveUncataloguedEntry(entry, selection.id);
+    }
+    const references = selection.references ?? [];
+    const referencesKey = JSON.stringify(references);
+    const cached = input.materializationCache?.get(selection.id);
+    if (cached !== undefined) {
+        return resolveCachedEntry(cached, referencesKey, selection.id);
+    }
+    const resolved = resolveCatalogSkill({
+        catalogEntry,
+        references,
+        profileReferenceRoot,
+        projectDirectory: input.projectDirectory,
+        outputDirectory: input.outputDirectory,
+    });
+    input.materializationCache?.set(selection.id, {
+        referencesKey,
+        generatedDirectory: resolved.generatedDirectory,
+    });
+    return { sources: toEntrySources(resolved.generatedDirectory), diagnostics: resolved.diagnostics };
+};
+const resolveCachedEntry = (cached, referencesKey, id) => {
+    if (cached.referencesKey !== referencesKey) {
+        return {
+            sources: [],
+            diagnostics: [
+                {
+                    severity: 'error',
+                    path: `controls.skills/${id}`,
+                    message: `Skill '${id}' is selected with conflicting reference sets across control scopes.`,
+                },
+            ],
+        };
+    }
+    return { sources: toEntrySources(cached.generatedDirectory), diagnostics: [] };
+};
+const toEntrySources = (generatedDirectory) => generatedDirectory === undefined ? [] : [generatedDirectory];
+const resolveUncataloguedEntry = (entry, id) => {
+    if (typeof entry !== 'string') {
+        return {
+            sources: [],
+            diagnostics: [
+                {
+                    severity: 'error',
+                    path: `controls.skills/${id}`,
+                    message: `Skill ID '${id}' does not resolve in any skills directory.`,
+                },
+            ],
+        };
+    }
+    if (isValidSkillId(entry)) {
+        return {
+            sources: [entry],
+            diagnostics: [
+                {
+                    severity: 'warning',
+                    path: `controls.skills/${entry}`,
+                    message: `Skill '${entry}' does not resolve in any skills directory; passing it through as a path source.`,
+                },
+            ],
+        };
+    }
+    return { sources: [entry], diagnostics: [] };
+};
+const resolveCatalogSkill = (input) => {
+    const { catalogEntry } = input;
+    const diagnostics = [];
+    const document = readSkillDocument(catalogEntry.skillPath);
+    if (isSkillDocumentIssue(document)) {
+        return { diagnostics: [{ severity: 'error', path: document.path, message: document.message }] };
+    }
+    if (document.name !== catalogEntry.id) {
+        return {
+            diagnostics: [
+                {
+                    severity: 'error',
+                    path: catalogEntry.skillPath,
+                    message: `SKILL.md 'name' ('${document.name}') must match its directory name ('${catalogEntry.id}').`,
+                },
+            ],
+        };
+    }
+    const materializations = planSkillMaterializations(input, document, diagnostics);
+    if (diagnostics.some((diagnostic) => diagnostic.severity === 'error') || input.outputDirectory === undefined) {
+        return { diagnostics };
+    }
+    const generatedDirectory = join(input.outputDirectory, catalogEntry.id);
+    cpSync(catalogEntry.directory, generatedDirectory, { recursive: true });
+    for (const materialization of materializations) {
+        const sectionDirectory = join(generatedDirectory, materialization.section);
+        mkdirSync(sectionDirectory, { recursive: true });
+        // copyFileSync preserves the source mode, so materialized scripts stay executable.
+        copyFileSync(materialization.sourcePath, join(sectionDirectory, materialization.destinationName));
+    }
+    return { generatedDirectory, diagnostics };
+};
+const planSkillMaterializations = (input, document, diagnostics) => {
+    const materializations = [];
+    for (const section of skillMaterializationSections) {
+        const entries = [
+            ...document[section].map((reference) => ({ reference, fileRoot: input.catalogEntry.referenceRoot })),
+            // Profile-added references resolve `file` from the declaring profile's repository.
+            ...(section === 'references'
+                ? input.references.map((reference) => ({
+                    reference,
+                    fileRoot: input.profileReferenceRoot ?? input.projectDirectory ?? input.catalogEntry.referenceRoot,
+                }))
+                : []),
+        ];
+        materializations.push(...planSectionMaterializations(input, section, entries, diagnostics));
+    }
+    return materializations;
+};
+const planSectionMaterializations = (input, section, entries, diagnostics) => {
+    const materializations = [];
+    const destinationNames = new Set();
+    for (const { reference, fileRoot } of entries) {
+        const resolved = resolveReferenceMaterialization({
+            reference,
+            section,
+            fileRoot,
+            projectDirectory: input.projectDirectory,
+            skillPath: input.catalogEntry.skillPath,
+        });
+        if (resolved === undefined) {
+            continue;
+        }
+        if ('message' in resolved) {
+            diagnostics.push(resolved);
+            continue;
+        }
+        if (destinationNames.has(resolved.destinationName)) {
+            diagnostics.push({
+                severity: 'error',
+                path: input.catalogEntry.skillPath,
+                message: `Destination '${section}/${resolved.destinationName}' is declared more than once.`,
+            });
+            continue;
+        }
+        // Checked against the source skill directory during planning so lint reports
+        // shipped-file collisions without materializing anything.
+        if (existsSync(join(input.catalogEntry.directory, section, resolved.destinationName))) {
+            diagnostics.push({
+                severity: 'error',
+                path: input.catalogEntry.skillPath,
+                message: `Destination '${section}/${resolved.destinationName}' collides with a file ` +
+                    `already shipped by skill '${input.catalogEntry.id}'.`,
+            });
+            continue;
+        }
+        destinationNames.add(resolved.destinationName);
+        materializations.push(resolved);
+    }
+    return materializations;
+};
+const describeReference = (reference, fileRoot, projectDirectory) => 'repo_file' in reference
+    ? { declaredPath: reference.repo_file, root: projectDirectory, kind: 'repo_file', rootLabel: 'project' }
+    : { declaredPath: reference.file, root: fileRoot, kind: 'file', rootLabel: 'catalog' };
+const resolveReferenceMaterialization = (input) => {
+    const { declaredPath, root, kind, rootLabel } = describeReference(input.reference, input.fileRoot, input.projectDirectory);
+    const error = (message) => ({
+        severity: 'error',
+        path: input.skillPath,
+        message,
+    });
+    if (root === undefined) {
+        return error(`Reference ${kind} '${declaredPath}' has no ${rootLabel} root to resolve from.`);
+    }
+    const sourcePath = isAbsolute(declaredPath) ? declaredPath : join(root, declaredPath);
+    if (!existsSync(sourcePath)) {
+        // A consuming project may not contain a repo_file target; the reference is omitted.
+        return kind === 'repo_file' ? undefined : error(`Reference file '${declaredPath}' was not found under '${root}'.`);
+    }
+    if (!statSync(sourcePath).isFile()) {
+        return error(`Reference ${kind} '${declaredPath}' must be a regular file.`);
+    }
+    if (escapesRoot(sourcePath, root)) {
+        return error(`Reference ${kind} '${declaredPath}' resolves outside its ${rootLabel} root '${root}'.`);
+    }
+    return { section: input.section, sourcePath, destinationName: basename(declaredPath) };
+};
+/** Targets must remain within their root after following symlinks. */
+const escapesRoot = (sourcePath, root) => {
+    let resolvedSource;
+    let resolvedRoot;
+    try {
+        resolvedSource = realpathSync(sourcePath);
+        resolvedRoot = realpathSync(root);
+    }
+    catch {
+        /* v8 ignore next 2 -- existsSync guards the source; a vanished root is a race we treat as escaping. */
+        return true;
+    }
+    const relativePath = relative(resolvedRoot, resolvedSource);
+    // A bare '..' or a '../' prefix escapes; a sibling name like '..config' does not.
+    return relativePath === '..' || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath);
+};
+//# sourceMappingURL=SkillResolution.js.map

package/dist/skills/SkillResolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SkillResolution.js","sourceRoot":"","sources":["../../src/skills/SkillResolution.ts"],"names":[],"mappings":"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"}

package/{doc → docs}/documentation/README.md

@@ -8,8 +8,11 @@ User-facing Outfitter documentation.
 - [First-time CLI agent users](./first-time-cli-agent-users.md)
 - [Switching to Outfitter](./switching-to-outfitter.md)
 - [Profiles](./profiles.md)
-- [Profile repositories](./profile-repository.md)
+- [Skills](./skills.md) — Define project and profile-bundled skills, route to specialized resources, and compose external references.
+- [Best practices](./best-practices.md) — Prefer a few stable profiles and many focused, progressively disclosed skills.
+- [Profile repositories](./profile-repository.md) — Publish and consume shareable profiles and standalone skills.
 - [Iterating on local and worktree profiles](./iterating-on-profiles.md)
+- [Running profiles in GitHub Actions](./actions.md)
 - [Adapter support matrix](./support-matrix.md)
 - [State persistence](./state.md)
 - [Philosophy](../philosophy.md)

package/docs/documentation/actions.md

@@ -0,0 +1,97 @@
+# Running profiles in GitHub Actions
+
+[`ai-outfitter/actions`](https://github.com/ai-outfitter/actions) runs an Outfitter profile non-interactively inside a GitHub Actions workflow. Outfitter assembles the profile exactly as it does locally — context, prompts, skills, controls — and launches the agent CLI in headless print mode (`pi -p`), so the agent does one unit of work per workflow run and exits. Wire it to any trigger and a profile becomes a CI agent: a PR reviewer, a scheduled commit auditor, an issue triager.
+
+```yaml
+# .github/workflows/issue-triage.yml
+name: Issue triage
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  contents: read
+  issues: write
+  models: read
+
+jobs:
+  triage:
+    if: github.event.issue.user.type != 'Bot'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ai-outfitter/actions@v1
+        with:
+          profile: issue-triage
+          profile-source: ${{ github.workspace }}/profiles
+          prompt: >-
+            Triage issue #${{ github.event.issue.number }} in
+            ${{ github.repository }} following your process.
+```
+
+The action installs `@ai-outfitter/outfitter`, writes a minimal `~/.outfitter/settings.yml` on the runner, syncs remote catalogs if needed, then runs `outfitter run --profile <profile> --agent pi -- -p "<prompt>"`. The runner is discarded afterwards; nothing persists except what the agent pushed through its token.
+
+Profiles can come from the checked-out repository itself (a path, as above), an `owner/repo` catalog shorthand, or any git URI — the same [profile repository](./profile-repository.md) sources Outfitter supports locally. Pin `profile-source-ref` for catalogs you don't own.
+
+## Pass GitHub trigger context
+
+`trigger_context` is a convention for the initial prompt passed by an
+`ai-outfitter/actions` workflow. It is not an Outfitter object and Outfitter does
+not create or parse it. GitHub Actions interpolates the selected `github`
+expression values before invoking Outfitter, giving the profile metadata that
+the workflow — not the event author — chose to pass. That does not make every
+value trustworthy: branch and tag names, labels, titles, and logins are
+user-influenced, so route on them as opaque identifiers and never treat them
+as instructions.
+
+```yaml
+- uses: ai-outfitter/actions@v1
+  with:
+    profile: platform
+    prompt: |
+      Handle this GitHub event according to the profile's skill activation rules.
+
+      trigger_context:
+        repository: ${{ github.repository }}
+        event_name: ${{ github.event_name }}
+        issue_number: ${{ github.event.issue.number || '' }}
+```
+
+Include only the identifiers the profile's routing rules need for the
+workflow's declared events (for example `sha`, `issue_labels`, or a
+deployment's `environment_url` when those events are in play). Add a
+workflow-owned discriminator, such as `report_kind: weekly-kpi`, when GitHub's
+event metadata cannot distinguish scheduled behaviors.
+
+Keep the profile's mapping from this metadata to skills short and keep task
+procedures in the skills themselves. See
+[Keep routing concise](./best-practices.md#keep-routing-concise) for that design
+boundary.
+
+Do not interpolate issue bodies, pull request bodies, comments, diffs,
+deployment logs, or fetched page content into `trigger_context`. Pass stable
+identifiers, select the relevant skill, and let that skill retrieve only the
+untrusted source material it needs with trusted tools.
+
+## Zero-key inference with GitHub Models
+
+CI agents don't need a paid provider key. [GitHub Models](https://docs.github.com/en/github-models) serves hosted models authenticated by the workflow's own `GITHUB_TOKEN`: grant `models: read` in the `permissions:` block, commit a pi provider config pointing at `https://models.github.ai/inference` with `"apiKey": "$GITHUB_TOKEN"`, install it to `~/.pi/agent/models.json` before the action step, and select the provider in the profile's `controls`. The action's README documents the full recipe, including model-selection gotchas (catalog availability, tool-call wire compatibility, and models too weak to hold an agentic loop).
+
+Mind the rate limits: the included tier is sized for event-driven, one-shot jobs. Concurrent runs of a large model can 429; high-volume review loops need a provider key.
+
+## Write profiles for headless runs
+
+A profile that behaves well interactively can still fail silently in CI. Lessons from running triage agents in production:
+
+- **Stdout is invisible.** In print mode nobody reads what the agent says — only its side effects matter. Instruct the profile to _do_ things with `gh` (comment, label, push) and name the exact commands; otherwise models will print the deliverable as their answer and exit green.
+- **Quote-safe posting.** When the agent posts text derived from untrusted input (issue bodies, diffs) back through `gh`, require a quoted heredoc plus `--body-file`, never inline `--body "..."` — backticks in a double-quoted body are executed by the shell.
+- **Verify side effects, not exit codes.** A green run is not proof of work. Add a post-agent step that asserts the expected side effects landed — the action ships [`scripts/validate-triage.sh`](https://github.com/ai-outfitter/actions/blob/main/scripts/validate-triage.sh) as a reference for triage-style jobs.
+- **Hard limits in the profile.** Enumerate exactly what the agent may do (which labels, how many comments, no closing/editing) and treat fetched content as data to classify, never instructions.
+
+## Scope the token
+
+The agent runs arbitrary `gh`/`git`/shell with whatever token you hand it, against untrusted input. Prefer the workflow's own `GITHUB_TOKEN` with an explicit least-privilege `permissions:` block; use a fine-grained PAT from a dedicated machine account only when the agent needs its own identity. Never use a human's PAT. The action's [token-permissions](https://github.com/ai-outfitter/actions/blob/main/docs/token-permissions.md) and [bot-account](https://github.com/ai-outfitter/actions/blob/main/docs/bot-account.md) guides cover this in depth, including prompt-injection trust boundaries.
+
+## More examples
+
+The action's [`examples/`](https://github.com/ai-outfitter/actions/tree/main/examples) directory covers scheduled commit review, PR ready-for-review reviews, sensitive-path audits, assigned-task agents, and zero-key issue triage on GitHub Models. A complete live setup — workflow, profile, provider config, and validation — runs in [`ai-outfitter/default-profiles`](https://github.com/ai-outfitter/default-profiles) as its own issue-triage agent.

package/docs/documentation/best-practices.md

@@ -0,0 +1,105 @@
+# Best practices
+
+Outfitter works best with a few stable profiles and many focused skills.
+Profiles define who the agent is and the boundaries it operates within. Skills
+define what the agent can progressively learn to do.
+
+## Prefer a few profiles and many skills
+
+Create a profile for a durable identity or policy boundary — engineering,
+platform operations, support, a customer persona. A profile owns model and
+provider controls, operating policy and safety boundaries, tools and
+permissions, conventions, and the short rules for selecting skills.
+
+Add a skill when the new behavior is a capability within an existing identity:
+issue planning, code review, deployment smoke testing, KPI reporting, release
+preparation. Adding a new situation SHOULD usually add a skill and a concise
+activation rule, not another profile. Reserve profile inheritance for genuine
+control and policy composition; do not require consumers to inherit a profile
+merely to access one of its skills.
+
+Prefer one profile with many skills:
+
+```text
+platform profile
+├── issue-planning skill
+├── issue-implementation skill
+├── kpi-reporting skill
+├── deployment-review skill
+└── failed-deployment-triage skill
+```
+
+Avoid separate `issue-planner`, `deployment-reviewer`, and `kpi-reporter`
+profiles when they share the same platform identity, permissions, and tools.
+Adding release notes later should add a `release-notes` skill to the platform
+profile, not a `release-notes-agent` profile with copies of the same controls.
+
+Separate profiles are appropriate when the policy boundary differs. An
+engineering agent may edit code, run tests, and push branches; a customer
+support agent may read customer conversations and draft replies but must not
+modify repositories. Those are different identities with different data access,
+tools, and write permissions, so separate `engineering` and `support` profiles
+are appropriate — and each can still expose many focused skills.
+
+## Keep skills focused
+
+Give each skill one recognizable capability and a description precise enough
+for an agent to decide when it applies. Keep common policy in the profile
+rather than repeating it across every skill.
+
+Focused does not mean tiny. Err on the side of one larger skill that
+[routes to different references](./skills.md#skills-as-routers) over many
+near-duplicate skills: split a skill only when its description can no longer
+say when it applies. Point references at existing human-maintained
+documentation rather than writing new agent-only copies, and use
+[profile-added references](./skills.md#profile-added-references) to specialize
+a shared skill instead of forking it.
+
+## Use references for human documentation
+
+Keep canonical architecture, policy, and operating documents in normal `docs/`
+locations where people already maintain and review them. Declare those files as
+skill `references` instead of copying them into skill directories, and read
+them only after the skill activates so every run does not pay the context cost
+of every possible workflow. See
+[External references](./skills.md#external-references) for the reference format
+and trust rules.
+
+## Keep routing concise
+
+A profile's system prompt can map stable runtime signals to relevant skills.
+Keep these activation rules short; detailed procedures belong in the selected
+skills and their references, never repeated in the profile prompt (see
+[Where context and instructions live](./skills.md#where-context-and-instructions-live)).
+
+```text
+Select only the skill relevant to the current task.
+- Planning request: use issue-planning.
+- Approved implementation request: use issue-implementation.
+- Recurring repository activity report: use kpi-reporting.
+- Successful environment awaiting verification: use deployment-review.
+- Failed environment update: use failed-deployment-triage.
+Load detailed task content only after selecting the skill.
+```
+
+When an integration launches the profile, pass only the trusted identifiers and
+runtime metadata needed to choose a skill. Keep untrusted source material out
+of the activation rules and let the selected skill retrieve only what it needs
+with trusted tools.
+
+## Keep automation reusable
+
+For agentic automation, prefer a small number of reusable workflows that pass
+concise runtime metadata to the same stable execution profile. Let that profile
+activate the appropriate skill. One profile and one workflow can then support
+issue planning, implementation, scheduled reporting, deployment review, and
+future situations; adding a capability becomes a skill change instead of
+another near-duplicate profile and automation job.
+
+## Review the trust chain
+
+Profiles and skills can influence agent behavior and tool use. Follow
+[Trust and review](./profile-repository.md#trust-and-review) for catalog
+sources, keep secrets out of profiles, skills, references, and prompts, and run
+`outfitter profile lint --strict` in CI to catch broken skill IDs and
+references before they reach an agent run.

package/{doc → docs}/documentation/profile-repository.md

@@ -1,6 +1,9 @@
 # Profile repositories
 
-A profile repository (also called a profile catalog) is a git repository that publishes Outfitter profiles so a team or organization can share them. You can bootstrap a machine or project from one, or add one as an ongoing profile source that Outfitter keeps synchronized.
+A profile repository (also called a profile catalog) is a git repository that
+publishes Outfitter profiles and skills so a team or organization can share
+them. You can bootstrap a machine or project from one, or add one as an ongoing
+source that Outfitter keeps synchronized.
 
 ```bash
 outfitter setup https://github.com/my_account/outfitter_config
@@ -15,6 +18,10 @@ outfitter_config/
   settings.yml
   profiles/
     engineering-default/profile.yml
+  skills/
+    outfitter-actions/SKILL.md
+  docs/
+    actions-design.md
 ```
 
 or a `.outfitter/` folder:
@@ -25,7 +32,11 @@ outfitter_config/
     settings.yml
     profiles/
       engineering-default/profile.yml
+    skills/
+      outfitter-actions/SKILL.md
     deepwork/jobs/
+  docs/
+    actions-design.md
 ```
 
 Inside the profiles directory, both profile layouts work:
@@ -35,6 +46,56 @@ Inside the profiles directory, both profile layouts work:
 
 See [Profiles](./profiles.md) for the full layout reference, inheritance, and prompt-include rules. A catalog can also publish a shared base profile marked `template: true` that role profiles inherit from without the base itself appearing as a launchable choice.
 
+## Publishing skills
+
+Publish a standalone skill under the catalog's `skills/<skill-id>/SKILL.md` or
+`.outfitter/skills/<skill-id>/SKILL.md`. The folder name is the skill ID, and the
+standard `name` in `SKILL.md` MUST match it. See [Skills](./skills.md) for the
+complete definition and reference format.
+
+Standalone catalog skills are independent of catalog profiles. A consumer can
+select one from an existing local profile without inheriting any profile from
+the publishing repository:
+
+```yaml
+# ~/.outfitter/settings.yml
+default_profile: platform
+default_agent: pi
+profile_sources:
+  - github: ai-outfitter/actions
+    ref: v1
+    path: .outfitter
+  - path: ./profiles
+```
+
+```yaml
+# ~/.outfitter/profiles/platform/profile.yml
+id: platform
+label: Platform
+
+controls:
+  skills:
+    - outfitter-actions
+```
+
+The catalog root is the directory containing `profiles/` (and `settings.yml`,
+when present). Outfitter discovers `skills/` beside `profiles/` at that root,
+so a catalog may publish standalone skills without publishing placeholder
+profiles. A source whose `path:` points directly at the profiles directory
+keeps working; its parent is the catalog root.
+
+Skill IDs follow the same [layer precedence](./concepts.md#layer-precedence) as
+profiles: project-local, project, user, then cached remote sources in
+configured order. Outfitter reports shadowed IDs so consumers can see which
+source supplies the selected skill.
+
+A published skill can reuse human-maintained catalog documentation without
+copying it into the skill folder: declare the document as a `file` reference,
+which resolves inside the catalog's checkout (including its synced cache),
+while `repo_file` references resolve inside the consumer's active project. See
+[External references](./skills.md#external-references) for the two-root model
+and trust rules.
+
 ## Consuming a catalog as a profile source
 
 Add the repository to `profile_sources` in your user (`~/.outfitter/settings.yml`) or project (`.outfitter/settings.yml`) settings:
@@ -61,7 +122,9 @@ Each source entry is one of:
 Remote entries (`github`/`uri`) additionally accept:
 
 - `ref:` — a tag, branch, or commit to pin. With a `ref`, `outfitter sync` fetches and checks out exactly that ref. Without one, sync fast-forwards the repository's default branch, so you always track the catalog's latest state.
-- `path:` — a subdirectory inside the repository that contains the profiles.
+- `path:` — the catalog root inside the repository (the directory containing
+  `profiles/` and, optionally, `skills/`), or the profiles directory itself as
+  in existing configurations — its parent is then the catalog root.
 - `only:` / `except:` — filter which profile ids from the source are exposed. `only` is an allowlist; `except` is a blocklist.
 
 ## Remote settings
@@ -94,18 +157,23 @@ Private GitHub catalogs are an enterprise feature. When sync detects a private G
 
 ## Trust and review
 
-Adding a catalog source means trusting its authors with your agent runtime. Profiles from a catalog can:
+Adding a catalog source means trusting its authors with your agent runtime.
+Profiles and selected skills from a catalog can:
 
 - **Inject extensions** into your agent launch (`controls.extensions`). Extensions are code that runs inside the agent process with full access to your system — files, network, and shell.
 - **Add arbitrary CLI arguments** (`controls.args`) to the launched agent, which can change permission modes or other agent behavior.
 - **Set environment variables** (`controls.environment`) for the agent process.
 - **Shape prompts, skills, subagents, and DeepWork jobs** — steering what the agent does with the access it already has.
+- **Provide skill references** — catalog `file` references are trusted with the
+  selected skill; see the [trust boundary](./skills.md#trust-boundary).
 
 Before adding a source, review it:
 
 1. Read every profile's `controls` — especially `extensions`, `args`, and `environment` — and any extension code the repository ships.
-2. Check `remote_settings` targets: a settings file can add further profile sources you did not review.
-3. Confirm the repository's ownership and that its maintainers are who you expect.
-4. Prefer `only:` filters so you expose just the profiles you reviewed.
+2. Read every selected skill and its catalog-owned `file` references.
+3. Check `remote_settings` targets: a settings file can add further profile sources you did not review.
+4. Confirm the repository's ownership and that its maintainers are who you expect.
+5. Prefer `only:` filters so you expose just the profiles you reviewed, and list
+   skills explicitly by ID in `controls.skills`.
 
 For organization catalogs, pin a `ref:` (a tag or commit) rather than tracking the default branch. A pinned ref makes updates an explicit, reviewable action — bump the ref after reviewing the diff — instead of silently pulling whatever the catalog publishes next. Unpinned sources are convenient for catalogs you maintain yourself, but they mean `outfitter sync` executes-by-configuration whatever landed upstream.