Skip to content

Markdown Imports

Starting with PromptScript v1.8, skills can be imported directly from Markdown files using @use. No need for npx skills, skills.sh, or any external installer.

Why markdown imports?

Traditional skill installation requires running an external tool (npx skills add ...) to copy files into .promptscript/skills/. Markdown imports let you reference skill files directly — local or remote — and PromptScript handles the rest at compile time.

Benefits:

  • No external tools required
  • Version-pinned reproducible builds via promptscript.lock
  • Works with local files, Git repositories, and directory bundles
  • Compatible with all existing @use features (aliases, @extend, params)

Syntax

Local file imports

Reference a .md file relative to the current .prs file:

@use ./skills/frontend-design.md
@use ./shared/commit.md as commit

Remote file imports (Go-module style)

Import directly from any Git repository by host path:

@use github.com/anthropics/skills/frontend-design@1.0.0
@use github.com/anthropics/skills/commit@^2.0.0       # semver range
@use github.com/anthropics/skills/code-review@main    # branch

Version pinning uses @ after the path segment. Omitting a version resolves to the latest default branch.

Directory imports

Import an entire skill directory (containing a SKILL.md):

@use github.com/repo/skills/gitnexus                  # imports gitnexus/SKILL.md
@use ./skills/my-tool                                  # imports ./skills/my-tool/SKILL.md

When the path resolves to a directory, PromptScript automatically loads SKILL.md from inside it and discovers any sibling resource files (see Resource files below).

Content detection

When PromptScript loads a .md file, it determines how to treat its content:

Content type How detected Behaviour
PromptScript (.prs in .md) File contains valid PRS block syntax Parsed as a .prs fragment and merged normally
Skill frontmatter YAML frontmatter with name / description fields Loaded as a skill definition
Raw markdown No PRS blocks, no skill frontmatter Treated as free-form knowledge content

This means you can point @use at any existing .md file — PromptScript picks the right interpretation automatically.

CLI: managing markdown imports

PromptScript v1.8 adds a prs skills subcommand for managing markdown-imported skills:

prs skills add github.com/anthropics/skills/commit@1.0.0
# Adds the import to your .prs file and updates promptscript.lock

prs skills remove commit
# Removes the @use line and lock entry for the skill

prs skills list
# Lists all markdown-imported skills with their resolved versions

prs skills update
# Re-resolves all markdown-imported skills to their latest matching versions
# and updates promptscript.lock

Both prs skills add and prs skills update clone the referenced ref, recompute the real sha256 integrity hash, and validate the SKILL.md frontmatter against the Agent Skills spec before touching promptscript.lock. Use --strict to treat warnings as errors (useful in CI) or --skip-validation to bypass the check when the upstream is in flux. Plain http:// sources are rejected to prevent MITM.

Lock file: version pinning

When a .prs file contains remote markdown imports, prs compile (or prs lock) generates a promptscript.lock file recording the exact resolved commit for each dependency:

# promptscript.lock (auto-generated — commit to version control)
imports:
  github.com/anthropics/skills/commit@1.0.0:
    resolved: github.com/anthropics/skills
    commit: a3f8c2d1b0e94567890abcdef1234567890abcde
    path: commit
  github.com/repo/skills/gitnexus:
    resolved: github.com/repo/skills
    commit: 9b2e1f0a3c84512367890abcdef1234567890abc
    path: gitnexus

Commit promptscript.lock to version control. This ensures every machine and CI run resolves to the same content, regardless of what has been pushed to the remote since.

Update a single import to the latest matching version:

prs skills update github.com/anthropics/skills/commit
prs lock --dry-run                    # Preview changes before applying

Resource files

When a markdown import resolves to a directory (e.g. github.com/repo/skills/gitnexus → gitnexus/SKILL.md), PromptScript automatically discovers and includes sibling resource files — data files, scripts, templates — that live in the same directory tree.

This mirrors the behaviour of locally installed skills:

gitnexus/
├── SKILL.md          # main skill definition
├── data/
│   └── repos.csv     # discovered automatically
└── scripts/
    └── query.py      # discovered automatically

All discovered files are copied to every compilation target alongside the skill, just as if the directory were in .promptscript/skills/.

Examples

Mix local and remote imports

@meta { id: "my-project" syntax: "1.1.0" }

# Remote skills with version pins
@use github.com/anthropics/skills/commit@1.2.0
@use github.com/anthropics/skills/code-review@^2.0.0

# Local skill file
@use ./skills/custom-lint.md as lint

@skills {
  commit: {
    description: "Create conventional commits"
    userInvocable: true
  }
  code-review: {
    description: "Review code for quality"
    userInvocable: true
  }
  lint: {
    description: "Run custom linting checks"
  }
}

Extend a remote skill

@use github.com/anthropics/skills/code-review@1.0.0 as review

@extend review.standards {
  extra: ["Check for our internal naming conventions"]
}

See Also