# 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](#resource-files) below).

A directory may also group several skills, each in its own subdirectory — every one of them is imported:

```
@use ./skills                    # imports skills/lint/SKILL.md, skills/review/SKILL.md, ...
```

A `SKILL.md` at the imported directory's own root wins over a skill of the same name found deeper down.

## 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:

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

prs skills add ./vendor/my-skill
# Local directory: validated and referenced in place, no lockfile entry

prs skills add ~/Downloads/skills/my-skill --copy
# Local directory: copied into .promptscript/skills/ and referenced there

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

prs skills list
# Lists imported skill paths

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` resolve the requested tag, branch, commit, or semver range to an exact commit. They clone that resolved ref, recompute the real `sha256` integrity hash, and validate the SKILL.md frontmatter against the [Agent Skills spec](https://agentskills.io/specification) before touching `promptscript.lock`. Every Git operation, including semver lookup, `ls-remote`, commit probes, cloning, and checkout, has a 60-second hard timeout with actionable failure output. Use `--strict` to treat warnings as errors (useful in CI) or `--skip-validation` to skip only frontmatter checks. Remote access, cloning, commit pinning, file checks, and integrity hashing still run. Plain `http://` sources are rejected to prevent MITM.
When a skill is added with a `git@` source, its canonical repository entry also stores `gitUrl` so later updates continue using SSH.
`prs skills add` writes the `.prs` file and lockfile as one user-visible transaction. If the second write fails, both files are restored when the lockfile still contains the command's update. A lockfile changed concurrently is left untouched, and the rollback conflict is reported explicitly.
Local sources skip the clone and the lockfile: the on-disk SKILL.md is validated with the same rules, a `@use` line is inserted, and no pin is recorded because there is no commit to pin.

For a repository owner entry with `source: md` and a `skills` list, `integrity` is an
aggregate SRI hash. PromptScript hashes a canonical JSON array containing each
managed child source key and its concrete child integrity, sorted by source key.
`prs lock`, `prs skills add`, and `prs skills update` recompute this value whenever
the owner is emitted or preserved. If a listed child is missing or has a pending
or otherwise incomplete integrity, the owner remains `sha256-pending`. Ordinary
registry dependencies and leaf Markdown entries are never aggregated. Existing
lockfiles remain valid and are refreshed when one of these commands next writes or
previews the lockfile.

## Lock file: version pinning

When a `.prs` file contains remote markdown imports, `prs skills add` or `prs lock` generates a `promptscript.lock` file recording the exact resolved commit for each dependency:

```yaml
# promptscript.lock (auto-generated - commit to version control)
version: 1
dependencies:
  https://github.com/anthropics/skills:
    version: 1.0.0
    commit: a3f8c2d1b0e94567890abcdef1234567890abcde
    integrity: sha256-5fb42506e17f17329465d2ef8c3a91f19ab030538395939b7c09d67d65868eb7
    source: md
    skills:
      - github.com/anthropics/skills/commit@1.0.0
  github.com/anthropics/skills/commit@1.0.0:
    version: 1.0.0
    commit: a3f8c2d1b0e94567890abcdef1234567890abcde
    integrity: sha256-4a74f088efbf7dc1df7cac0877869c26f6119db1f9f5f2703f5de7388ca36d9f
    source: md
```

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:

```bash
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/`. This holds for every shape a directory import can take: the imported directory may be the skill itself (`SKILL.md` at its root), may contain skill subdirectories, or may nest them under `skills/`.

Files listed in the `references:` and `scripts:` frontmatter arrays are loaded as well, and a missing entry is reported as a compilation error. The same [security limits](https://getpromptscript.dev/guides/local-skills/index.md#resource-files) as local skills apply — test directories, build output and system files are skipped.

## 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

- [npx skills](https://getpromptscript.dev/guides/npx-skills/index.md) - Alternative: install skills with the `skills` CLI
- [Local Skills](https://getpromptscript.dev/guides/local-skills/index.md) - Full reference for skill resolution and resource handling
- [Building Skills](https://getpromptscript.dev/guides/building-skills/index.md) - Create skills from scratch
- [Skill Contracts](https://getpromptscript.dev/guides/skill-contracts/index.md) - Define typed inputs and outputs