Skip to content

Skills and Resources

Skills package reusable agent capabilities. A skill can contain instructions, invocation metadata, input and output contracts, references, assets, and executable scripts.

PromptScript resolves each skill once and emits the target-native representation supported by each configured AI platform.

Inline Skill

@skills {
security-review: {
description: "Review code for application security risks"
userInvocable: true
disableModelInvocation: false
allowedTools: ["Read", "Grep", "Bash"]
content: """
Review authentication, authorization, secret handling, input validation,
dependency risk, and unsafe command execution.
"""
}
}
Try in Playground

Directory Skill

Portable skills can use a complete directory:

.promptscript/skills/security-review/
├── SKILL.md
├── LICENSE
├── references/
│ └── threat-model.md
├── scripts/
│ └── scan.sh
└── assets/
└── report-template.md

SKILL.md frontmatter declares resources and scripts:

---
name: security-review
description: Review code for application security risks
license: MIT
compatibility: Requires shell access
metadata:
owner: security
allowed-tools: 'Read Grep Bash'
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 producing native skill files. Script invocation and executable file modes remain platform and operating-system specific.

A skill can be declared in @skills and also have a SKILL.md in .promptscript/skills/. The declaration can sit in the entry file or in an imported fragment, the two are merged. When both give a description, the .prs one is used, also in the generated frontmatter, and a warning names both files. Skills in .promptscript/skills/ that no file declares are added once, by the entry file.

Skill Capabilities

CapabilityPurpose
descriptionDiscovery and invocation guidance
license and compatibilityNative skill metadata
metadataAdditional native skill metadata
contentMain skill instructions
allowedTools / allowed-toolsTool permissions
userInvocableManual user invocation
disableModelInvocationPrevent automatic model invocation
contextInherit or fork execution context
agentSelect agent type
modelSelect the model for the skill
requiresDeclare skill dependencies
referencesBundle supporting documents
scriptsBundle executable helpers
inputs and outputsDefine typed skill contracts
paramsParameterize reusable skills
examplesAttach focused examples

model sets the model used while the skill is active. Claude Code and Grok Build write it to the skill file, mapped through the model catalog the same way as agent models. Other targets have no skill model field and leave it out.

For skills backed by a SKILL.md file, a model set in .prs wins over the SKILL.md frontmatter, and a frontmatter model without a .prs one is mapped the same way. A model the target cannot run is left out of the skill file and reported with a PS4004 warning during compilation.

Universal and Native Paths

PromptScript can discover shared skills from the universal .agents/skills/ directory:

universalDir: .agents

Target formatters then emit native paths such as:

  • .claude/skills/<name>/SKILL.md
  • .github/skills/<name>/SKILL.md
  • .factory/skills/<name>/SKILL.md
  • .opencode/skills/<name>/SKILL.md
  • .agents/skills/<name>/SKILL.md

Gemini full mode emits interoperable .agents/skills/<name>/skill.md files alongside native commands under .gemini/commands/.

Path Tokens

Skill text often points at the skill’s own files. A fixed path like .factory/skills/lint/check.py is wrong once the same skill compiles for Claude Code. Write a path token instead and every target writes its own path:

TokenClaude Code exampleFactory example
{{prs.dotDir}}.claude.factory
{{prs.skillsDir}}.claude/skills.factory/skills
{{prs.skillDir}}.claude/skills/lint.factory/skills/lint
@skills {
lint: {
description: "Lint changed files"
content: """
Run `python {{prs.skillDir}}/check.py` on the changed files.
For formatting use the script in {{prs.skillsDir}}/format.
"""
}
}
Try in Playground

Tokens work in every generated file, so agents and commands can use {{prs.dotDir}} and {{prs.skillsDir}} too. {{prs.skillsDir}} follows skillBaseDir when it is set. {{prs.skillDir}} has a value only in the files of a skill directory; anywhere else, and for a target without such a directory, the token stays as written and compilation reports a PS4002 warning. Only these exact tokens are replaced, other {{...}} text such as Mermaid hexagons {{"label"}} is not touched. Write \{{prs.dotDir}} to keep the token itself in the output.

Filter Skills Per Target

id: filtered-skills-project
syntax: '1.4.0'
targets:
- factory:
version: full
includeSkills:
- security-review
- release
- claude:
version: full
includeSkills: true

Use skillBaseDir when generating skills inside a plugin, package, or nested monorepo build:

builds:
payments:
output: packages/payments
targets:
- factory:
version: full
skillBaseDir: .factory/skills

Import Skills

Skills can come from local files, registries, or Git repositories:

@use ./skills/security-review.md
@use @company/skills/release@^2.0.0
@use github.com/acme/agent-skills/[email protected]

Remote references are recorded in promptscript.lock with commit and integrity information.