# Agent Platform Examples

These examples cover core agent-platform capabilities. Open the
[Playground](/playground/) and choose **Complete Agent Platform** or
**Regular Field Replacement** to compile the same examples in your browser.

PromptScript 1.16 task examples:

| Task                            | Example                                             |
| ------------------------------- | --------------------------------------------------- |
| Predict composition results     | [Composition and Order](https://getpromptscript.dev/examples/composition-and-order/index.md)   |
| Choose merge or replacement     | [Merge vs Replace](https://getpromptscript.dev/examples/merge-vs-replace/index.md)             |
| Fix PS038 shape warnings        | [Fix Block Shape Warnings](https://getpromptscript.dev/examples/fix-block-shapes/index.md)     |
| Customize generated titles      | [Custom Section Headers](https://getpromptscript.dev/examples/custom-section-headers/index.md) |
| Build portable lifecycle policy | [Portable Hooks](https://getpromptscript.dev/examples/portable-hooks/index.md)                 |

## Complete Agent Platform

This syntax 1.6 example connects reusable skills, MCP tools, a specialist agent, lifecycle
automation, a release workflow, and a plugin bundle:

```promptscript
@meta {
  id: "checkout-agent-platform"
  syntax: "1.5.0"
  tags: ["payments", "typescript"]
}

@identity {
  """
  You are working on a payment service.
  Preserve transaction integrity and auditability.
  """
}

@standards {
  code: ["Use strict TypeScript", "Write tests for business rules"]
}

@skills {
  security-review: {
    description: "Review payment changes for security risks"
    allowedTools: ["Read", "Grep", "Bash"]
    content: """
      Inspect authentication, authorization, secrets, and payment data handling.
      Report findings by severity and include concrete remediation steps.
    """
  }
}

@mcpServers {
  issue-tracker: {
    transport: "stdio"
    command: ["node", "./tools/issues.mjs"]
    timeoutMs: 30000
  }
}

@agents {
  reviewer: {
    description: "Review changes before merge"
    tools: ["Read", "Grep", "Glob", "Bash"]
    model: "sonnet"
    skills: ["security-review"]
    mcpServers: ["issue-tracker"]
    content: "Review changed code, tests, and operational impact."
  }
}

@hooks {
  validate-changes: {
    event: "post-tool-use"
    matcher: "Edit|Write"
    command: ["pnpm", "run", "typecheck"]
    timeoutMs: 120000
    statusMessage: "Checking TypeScript"
  }
}

@workflows {
  release: {
    description: "Validate and prepare a release"
    content: """
      1. Review changes since the previous release
      2. Run formatting, linting, type checks, and tests
      3. Summarize changes and prepare release metadata
      4. Stop before publishing and request approval
    """
  }
}

@plugins {
  payment-engineering: {
    description: "Payment engineering capability bundle"
    version: "1.0.0"
    skills: ["security-review"]
    hooks: ["validate-changes"]
    mcpServers: ["issue-tracker"]
  }
}
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMAA6rQYIgATRIJFMcMRgGtmAVywBaDAHNOW8tjDNqJeWIlwAnuwyFZ8gIwUArBQAM58YIE64s5HlMKz52OHk6ORAsKzR4RmoINCx5AF0xAF8xMW5pfQgY4Qso8xBigE11QQxqGEEAdxNlCFYdQTZqwWDQrEE4GGoANwhGGApigAVa-qG6rGoMVjgMRiwIDpaOHUTCxalqtSkCjAAjaAKrce9SryzWHLgBVikaqTgi7xYpGAD5AFV+n15iNegAVWIwADKCSSKRAkXkAHUdnN4Fh3sZqIITmo4C14O9qGpYOEQOlWHcHs0oFB3qJvP1GGodlZNLVhjB6rJ6RIJN84DDkutWA4QAAlGAc+pdDAhfSCRg4RZ6DEmPpKZkXQSJODKUnFCQYGnMeowKSg5jMWm-cUwDBSCJRADitTQjvkACEMHAcGkDQq2Bx2KKbt5eYIAJJLOKrA64fKMbDCyIYDQ4EwQABeSbYkUZtXRKeeMrl7EELwEgiVzygLR0V3DEglaBMvUgzzr7xOVnVgwGWr2klYjCghzqLGHBbqtT4Rxz4keMDQcAbvJuZW8d0prF4jDQkIGfdoHwkEDgcDUME08xWygG3P9N+jrdFjyOzC84ZYJBIextrGYb53RACgAHosEtWlQLPC94AoEgACtSXJcM1j4dQsAAWX8QQAGZ3AIzxN0ybId10fQ6WKdkIE5e8T15flBTWNhRQlKUFWrFVsRgTE6j4ag9E-XkIKtHDAlte1gJdJcpKgZgTmAr0fT9MNBBIQCYCgV82FYfghMsalrUEcTGU1GI2UlGj6hU8MSD3A9ZloG0YMva8FhUAYbN5CcgywVjLM5DjlTNANvkiDhHjgIt9mYOIFmY1gjUkMgViwcYNwkLdSO4dNmD1ejBiNaRsCvRVgpwnleUlfRRRbR5r0gzRcRgfS1OwRU6PkABRI4sAAH2RAoWoy7zmB-P9jKCVg0DMeEoiJe45vkGIY0UFQvIkNCYAw7DZEcAAmQiiPDR5sFxTCCXI0UAGE1uaVpBHBOJoUSZIhKy+4d0aahlDAOT6ko7xalgb0fnovl4lehLRQANSKis6kHGglxqRHtU0u1+lanyapKMoRvDZxBDYqygtaeA+haUYfEULpqPUQkMdB-0JH2ihibUcRMV-LA1laSJa3YOtwohDilD1aKfDRcJVIkXD2chNRxsSTNx04imkddVH0ZBwE+AECsMBZwQABYFYgtBuN4ro1BOWsfTrapi1qABHS9HmqNAaGYQqoH9ddig+nJyDUHQWkBiRun0TRODD3T+1aB9VMYqHhVFCZZR6QRY-xBO2kTTAzlrQocRrYb-SPPEWKiZx3A8VrdWgIyTI1FkLKlDaq0tPUbV94qOE0MryeQ-07P3Q8BjE+QXKvG8POoLytxADJUgYfRqCsfAiFIcgxhoegQEr4V8EcZegA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

The references between blocks are validated before output is generated:

- The `reviewer` agent preloads `security-review` and receives access to `issue-tracker`.
- The plugin groups the skill, hook, and MCP server as one capability bundle.
- Rich target modes emit native agent, skill, MCP, hook, workflow, and plugin files where supported.

Use full target modes to generate native capability files:

```yaml
id: checkout-agent-platform
syntax: '1.5.0'

targets:
  - claude:
      version: full
  - cursor:
      version: full
  - factory:
      version: full
  - codex:
      version: full
```

## Regular Field Replacement

Syntax 1.3 introduced `field!: value` inside regular `@extend` blocks. Marked fields replace their
complete previous value, while unmarked fields retain normal merge behavior:

For new syntax 1.6 projects, prefer `@override` when replacing a complete
existing target. See [Merge vs Replace](https://getpromptscript.dev/examples/merge-vs-replace/index.md).

```promptscript
@meta {
  id: "field-replacement"
  syntax: "1.3.0"
}

@identity {
  """
  You are a TypeScript development assistant.
  """
}

@standards {
  testing: ["Use Jest", "Use integration tests"]
  linting: ["Use ESLint"]
  deployment: {
    platform: "Kubernetes"
    regions: ["us-east-1"]
  }
}

@extend standards {
  testing!: ["Use Vitest", "Follow the AAA pattern"]
  linting: ["Run lint checks before commits"]
  deployment!: {
    platform: "Cloud Run"
    regions: ["us-central1", "europe-west1"]
  }
}
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMAA6rQYIgATRIJHgIMKFIC01GOQyMYfdvLES4AT3YZCs+QEYKAZgoAGfawC+Ysd2mcsELEeEG5EH0g8UEATWYAV0EMdRjBABUjNBgAZUZqCDQsQSkYADclZjRdHIw4OAg4AXYKAOCnV1Z3aoxWKVipOH9QjmqIVgBzWWR5AFU4GEEAKXgseTpAiamBjkHqbAg2QT6sOHkAXQCoVYHhwVGQZcEAUVSAGVXDgLzyZiNS2VFQiU0sMGY1BIFhAAGlIgAjGDUVj8eBOCQSdSDLasOAjeSROAqGDlLAqSzPUJNJruIgcdqCVrtTrdb4SXZnACEGKuk0EADUfHMFoEAGLMKBQZgAdx2OCmAEFpYJMFgODCiRITuwzqyAEqRcQqnKMCWMADW3ShALiLBIJB8+xAR1Cr2FHy8LJ6iNlUGwpuBgQAwsLIlJBJrmiFXcjUeiLpjsdp2BsoISQIt5DBItRijAVCK5gnbRISSBnAcGF5qEZ8ERSOQYFRaImQIVaKj8JYC0A" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

The resolved standards use only the new `testing` and `deployment` values. The `linting` array
contains both entries because it was not marked for replacement.

## Portable Skill Resources

Directory skills can bundle supporting references, scripts, assets, contracts, and licenses:

```text
.promptscript/skills/security-review/
|-- SKILL.md
|-- LICENSE
|-- references/
|   `-- threat-model.md
|-- scripts/
|   `-- scan.sh
`-- assets/
    `-- report-template.md
```

Declare the bundled files and typed contract in `SKILL.md`:

```yaml
---
name: security-review
description: Review code for application security risks
references:
  - references/threat-model.md
scripts:
  - scripts/scan.sh
inputs:
  path:
    type: string
    description: Path to review
outputs:
  report:
    type: string
    description: Review report
---
Review selected code and use bundled references when evaluating risk.
```

PromptScript preserves the directory structure when emitting native skill packages.

## Monorepo Build Profiles

Named builds compile scoped agent configuration for multiple packages from one repository. A payments platform with two services keeps one shared team config and one entry per service:

```text
payments-platform/
├── .promptscript/
│   ├── team.prs            # Shared team config
│   ├── api.prs             # payments-api entry
│   └── web.prs             # checkout-web entry
├── packages/
│   ├── api/
│   └── web/
└── promptscript.yaml
```

Create the shared team config, `.promptscript/team.prs`. Both service entries inherit it, so team rules live in exactly one file:

```promptscript
@meta {
  id: "payments-team"
  syntax: "1.5.0"
  tags: ["payments"]
}

@identity {
  """
  You work on the ACME payments platform.
  Preserve transaction integrity and auditability.
  """
}

@standards {
  code: ["Use strict TypeScript", "Write tests for business rules"]
  testing: ["Use Vitest with the AAA pattern", "Cover failure and retry paths"]
}

@restrictions {
  - "Never log PAN, CVV, or raw webhook secrets"
}
```

<!-- playground-link-start -->
<a href="https://getpromptscript.dev/playground/?s=N4IgZglgNgpgziAXAbVABwIYBcAWSQwAeGAtmrAHRoBOCANCAMYD2AdljO-gAIkxYYABMAA6rQYIgATRIJEhMATz7s4AWg6l5YiXEXsMhWfICMFAKwUADNvGCBAczizk8pSqxx5AXTEBfMTFuaU4sCCxFYR05EG1YuwBNZgBXQQB3ZmoAa0E2exwYQQBBAGEAWQBRQXdQuGqobDBMkgpogAVqeBhqADdCrGoMVjgMRjC8iHYYB2pwyKGpQQxkqXCMACNoOda7ONsA1iC4AVYpDGopOtE7FikYF3kAVThC49mxwQAVRTQYAGVGLM0Fh5HQYgB1WYcezwTyCJrUQTrZJwSbwOrUZKwLwgXx2DjHSYOB4gZ6FABq4Vh6XCOHyhSKjOq2A41EOIDB8hKzD6iLAGGgyU6S1Ogk6A0imFwOLxByCnTeEDGEDYV2iahiADkYLzBFBmA5BG0ipqwSVyeSwZkxRg0ukYOscMxmDkXoD+Dj-CA-N4GKFqIp8ERSOQYFRaByQLzUWx8CZvUA" target="_blank" rel="noopener noreferrer">
  <img src="https://img.shields.io/badge/Try_in-Playground-blue?style=flat-square" alt="Try in Playground" />
</a>
<!-- playground-link-end -->

Each entry inherits the team config and adds only service-specific blocks. `.promptscript/api.prs`:

<!-- playground-link-skip -->

```promptscript
@meta {
  id: "payments-api"
  syntax: "1.5.0"
}

@inherit ./team

@context {
  service: "payments-api"
  framework: "Fastify"
  owns: ["authorization", "retries"]
}

@agents {
  api-reviewer: {
    description: "Review payments-api changes before merge"
    tools: ["Read", "Grep", "Glob", "Bash"]
    model: "sonnet"
    content: "Inspect handlers, tests, and migration impact. Reject changes that weaken idempotency."
  }
}
```

`.promptscript/web.prs`:

<!-- playground-link-skip -->

```promptscript
@meta {
  id: "checkout-web"
  syntax: "1.5.0"
}

@inherit ./team

@context {
  service: "checkout-web"
  framework: "React 18"
  owns: ["checkout flow", "payment forms"]
}

@skills {
  payment-forms: {
    description: "Review payment form changes for PCI and a11y risk"
    allowedTools: ["Read", "Grep"]
    content: "Check card-data handling, error states, and keyboard access in checkout forms."
  }
}
```

Declare one build profile per service in `promptscript.yaml`:

```yaml
builds:
  api:
    entry: .promptscript/api.prs
    output: packages/api
    targets:
      - factory:
          version: full
      - codex:
          version: full
          output: AGENTS.override.md
          agentsFile: AGENTS.override.md
  web:
    entry: .promptscript/web.prs
    output: packages/web
    targets:
      - cursor:
          version: full
```

Validate every entry, then compile each build separately:

```bash
prs validate .promptscript/team.prs .promptscript/api.prs .promptscript/web.prs --strict
prs compile --build api
prs compile --build web
prs compile --all-builds
```

In CI, fan the builds out through a matrix so each service validates and compiles in its own job:

```yaml
# .github/workflows/promptscript.yml
name: PromptScript

on:
  pull_request:
  push:
    branches: [main]

jobs:
  promptscript:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        build: [api, web]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm install -g @promptscript/cli@1.19.1
      - run: prs validate .promptscript/team.prs .promptscript/${{ matrix.build }}.prs --strict
      - run: prs compile --build ${{ matrix.build }} --dry-run
```

## Related Documentation

- [Agent Platform](https://getpromptscript.dev/features/index.md)
- [Agents](https://getpromptscript.dev/features/agents/index.md)
- [Skills and Resources](https://getpromptscript.dev/features/skills/index.md)
- [MCP Servers and Plugins](https://getpromptscript.dev/features/integrations/index.md)
- [Hooks and Workflows](https://getpromptscript.dev/features/automation/index.md)
- [Configuration Reference](https://getpromptscript.dev/reference/config/index.md#builds)