@ai-outfitter/outfitter 0.9.0 → 0.11.0

package/dist/skills/SkillResolution.js

@@ -0,0 +1,369 @@
+// Resolves selected skill IDs, validates references, and materializes generated skills.
+import { copyFileSync, cpSync, existsSync, globSync, mkdirSync, readdirSync, 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 });
+        const destinationPath = join(sectionDirectory, materialization.destinationName);
+        // Both copies preserve the source mode, so materialized scripts stay
+        // executable. Directory targets dereference symlinks that the contained
+        // scan already validated, so the generated skill is self-contained.
+        if (materialization.kind === 'directory') {
+            copyDirectoryDereferenced(materialization.sourcePath, destinationPath);
+        }
+        else {
+            copyFileSync(materialization.sourcePath, destinationPath);
+        }
+    }
+    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 destinationSources = new Map();
+    for (const { reference, fileRoot } of entries) {
+        const outcomes = resolveReferenceMaterializations({
+            reference,
+            section,
+            fileRoot,
+            projectDirectory: input.projectDirectory,
+            skillPath: input.catalogEntry.skillPath,
+        });
+        for (const resolved of outcomes) {
+            if ('message' in resolved) {
+                diagnostics.push(resolved);
+                continue;
+            }
+            const collision = describeDestinationCollision(input, section, resolved, destinationSources);
+            if (collision !== undefined) {
+                diagnostics.push({ severity: 'error', path: input.catalogEntry.skillPath, message: collision });
+                continue;
+            }
+            destinationSources.set(resolved.destinationName, resolved.sourcePath);
+            materializations.push(resolved);
+        }
+    }
+    return materializations;
+};
+/** Reports a destination claimed twice or already shipped inside the skill directory. */
+const describeDestinationCollision = (input, section, resolved, destinationSources) => {
+    const previousSource = destinationSources.get(resolved.destinationName);
+    if (previousSource !== undefined) {
+        return (`Destination '${section}/${resolved.destinationName}' is declared more than once ` +
+            `(by '${previousSource}' and '${resolved.sourcePath}').`);
+    }
+    // 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))) {
+        return (`Destination '${section}/${resolved.destinationName}' collides with a file ` +
+            `already shipped by skill '${input.catalogEntry.id}'.`);
+    }
+    return undefined;
+};
+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 targetError = (skillPath, message) => ({
+    severity: 'error',
+    path: skillPath,
+    message,
+});
+/**
+ * Resolves one reference entry to its materializations: one for a literal
+ * target, one per match for a glob target, and none for an omitted missing
+ * `repo_file` target.
+ */
+const resolveReferenceMaterializations = (input) => {
+    const { declaredPath, root, kind, rootLabel } = describeReference(input.reference, input.fileRoot, input.projectDirectory);
+    if (root === undefined) {
+        return [
+            targetError(input.skillPath, `Reference ${kind} '${declaredPath}' has no ${rootLabel} root to resolve from.`),
+        ];
+    }
+    const context = { root, kind, rootLabel, section: input.section, skillPath: input.skillPath };
+    if (isGlobPattern(declaredPath)) {
+        return expandGlobMaterializations(declaredPath, context);
+    }
+    const resolved = resolveTargetMaterialization(declaredPath, context);
+    return resolved === undefined ? [] : [resolved];
+};
+/**
+ * Matches when a target uses glob syntax instead of naming one literal path.
+ * Only the gitignore-style metacharacters count; braces are literal path
+ * characters, so a braced filename resolves as a literal target.
+ */
+const isGlobPattern = (declaredPath) => /[*?[]/u.test(declaredPath);
+/**
+ * Expands a glob target against its root. Each match then follows the same
+ * rules as a literal target, so a matched directory materializes recursively
+ * while an escaping or special match fails validation individually.
+ */
+const expandGlobMaterializations = (pattern, context) => {
+    // Braces are literal path characters in this contract, but globSync
+    // brace-expands them textually and offers no escape, so mixing them with
+    // glob syntax fails validation rather than silently matching other paths.
+    if (/[{}]/u.test(pattern)) {
+        return [
+            targetError(context.skillPath, `Reference ${context.kind} glob '${pattern}' must not contain braces; ` +
+                `braces are literal path characters, not glob syntax.`),
+        ];
+    }
+    // Sorted so diagnostics and collisions are deterministic across platforms.
+    const matches = globSync(pattern, { cwd: context.root }).sort();
+    if (matches.length === 0) {
+        // A consuming project may not contain repo_file matches; the reference is omitted.
+        return context.kind === 'repo_file'
+            ? []
+            : [targetError(context.skillPath, `Reference file glob '${pattern}' matched no files under '${context.root}'.`)];
+    }
+    const resolved = [];
+    for (const match of matches) {
+        const outcome = resolveTargetMaterialization(match, context);
+        if (outcome !== undefined) {
+            resolved.push(outcome);
+        }
+    }
+    return resolved;
+};
+/** Validates one concrete target path — a literal target or a single glob match. */
+const resolveTargetMaterialization = (targetPath, context) => {
+    const { root, kind, rootLabel, skillPath } = context;
+    const error = (message) => targetError(skillPath, message);
+    const sourcePath = isAbsolute(targetPath) ? targetPath : join(root, targetPath);
+    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 '${targetPath}' was not found under '${root}'.`);
+    }
+    const stats = statSync(sourcePath);
+    if (!stats.isFile() && !stats.isDirectory()) {
+        return error(`Reference ${kind} '${targetPath}' must be a regular file or directory.`);
+    }
+    if (escapesRoot(sourcePath, root)) {
+        return error(`Reference ${kind} '${targetPath}' resolves outside its ${rootLabel} root '${root}'.`);
+    }
+    const directoryIssue = describeDirectoryTargetIssue(stats, sourcePath, targetPath, context);
+    if (directoryIssue !== undefined) {
+        return error(directoryIssue);
+    }
+    return {
+        section: context.section,
+        sourcePath,
+        destinationName: basename(targetPath),
+        kind: stats.isDirectory() ? 'directory' : 'file',
+    };
+};
+/** Describes the first escaping, cyclic, or special path inside a directory target, if any. */
+const describeDirectoryTargetIssue = (stats, sourcePath, targetPath, context) => {
+    if (!stats.isDirectory()) {
+        return undefined;
+    }
+    const issue = scanDirectoryTarget(sourcePath, context.root, [realpathSync(sourcePath)], new Set());
+    if (issue === undefined) {
+        return undefined;
+    }
+    const containedPath = relative(sourcePath, issue.path);
+    const problemDescriptions = {
+        escaping: `which resolves outside its ${context.rootLabel} root '${context.root}'`,
+        cyclic: 'which creates a symlink cycle',
+        special: 'which is not a regular file or directory',
+    };
+    return (`Reference ${context.kind} '${targetPath}' contains ` + `'${containedPath}', ${problemDescriptions[issue.problem]}.`);
+};
+/**
+ * Finds the first path inside a directory target whose realpath escapes the
+ * reference root, a symlink that cycles back into an ancestor directory, or an
+ * entry that is neither a regular file nor a directory. Directory
+ * materialization dereferences symlinks recursively, so an escaping link would
+ * smuggle outside content into the generated skill, a cyclic link would never
+ * finish copying, and a special file such as a FIFO could block the copy.
+ */
+const scanDirectoryTarget = (directory, root, 
+/** Realpaths of the directories on the current descent, for cycle detection. */
+ancestry, 
+/** Realpaths of fully scanned directories, so shared subtrees scan once. */
+scanned) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const entryPath = join(directory, entry.name);
+        if (escapesRoot(entryPath, root)) {
+            return { path: entryPath, problem: 'escaping' };
+        }
+        // statSync follows symlinks, so in-root symlinked subdirectories are
+        // scanned too and a link to a special file is rejected like the file itself.
+        const entryStats = statSync(entryPath);
+        if (!entryStats.isFile() && !entryStats.isDirectory()) {
+            return { path: entryPath, problem: 'special' };
+        }
+        if (!entryStats.isDirectory()) {
+            continue;
+        }
+        const resolvedEntryPath = realpathSync(entryPath);
+        if (ancestry.includes(resolvedEntryPath)) {
+            return { path: entryPath, problem: 'cyclic' };
+        }
+        if (!scanned.has(resolvedEntryPath)) {
+            scanned.add(resolvedEntryPath);
+            const issue = scanDirectoryTarget(entryPath, root, [...ancestry, resolvedEntryPath], scanned);
+            if (issue !== undefined) {
+                return issue;
+            }
+        }
+    }
+    return undefined;
+};
+/**
+ * Copies a directory target while dereferencing symlinks, so the generated
+ * skill has no links back into catalog or project checkouts. cpSync's
+ * dereference option only follows the top-level source path, so nested entries
+ * are walked explicitly; copyFileSync preserves each file's mode.
+ */
+const copyDirectoryDereferenced = (source, destination) => {
+    mkdirSync(destination, { recursive: true });
+    for (const entry of readdirSync(source, { withFileTypes: true })) {
+        const sourcePath = join(source, entry.name);
+        const destinationPath = join(destination, entry.name);
+        // statSync follows symlinks; scanDirectoryTarget already rejected cycles.
+        if (statSync(sourcePath).isDirectory()) {
+            copyDirectoryDereferenced(sourcePath, destinationPath);
+        }
+        else {
+            copyFileSync(sourcePath, destinationPath);
+        }
+    }
+};
+/** 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.