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. """ }}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.mdSKILL.md frontmatter declares resources and scripts:
---name: security-reviewdescription: Review code for application security riskslicense: MITcompatibility: Requires shell accessmetadata: owner: securityallowed-tools: 'Read Grep Bash'references: - references/threat-model.mdscripts: - scripts/scan.shinputs: path: type: string description: Path to reviewoutputs: 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
| Capability | Purpose |
|---|---|
description | Discovery and invocation guidance |
license and compatibility | Native skill metadata |
metadata | Additional native skill metadata |
content | Main skill instructions |
allowedTools / allowed-tools | Tool permissions |
userInvocable | Manual user invocation |
disableModelInvocation | Prevent automatic model invocation |
context | Inherit or fork execution context |
agent | Select agent type |
model | Select the model for the skill |
requires | Declare skill dependencies |
references | Bundle supporting documents |
scripts | Bundle executable helpers |
inputs and outputs | Define typed skill contracts |
params | Parameterize reusable skills |
examples | Attach 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: .agentsTarget 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:
| Token | Claude Code example | Factory 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. """ }}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-projectsyntax: '1.4.0'
targets: - factory: version: full includeSkills: - security-review - release - claude: version: full includeSkills: trueUse skillBaseDir when generating skills inside a plugin, package, or nested monorepo build:
builds: payments: output: packages/payments targets: - factory: version: full skillBaseDir: .factory/skillsImport Skills
Skills can come from local files, registries, or Git repositories:
@use ./skills/security-review.md@use @company/skills/release@^2.0.0Remote references are recorded in promptscript.lock with commit and integrity information.