Configuration | Docs | Skillporter

Skillporter works with no configuration. diagnose, scan and add all run in a bare repository. Configuration exists so a team can declare what it wants and reproduce it.

File	Purpose	Commit it
`skillporter.yaml`	The manifest: which skills, which harnesses, which policy.	Yes
`skillporter.lock`	The exact content that was installed.	Yes
`.skillporter/`	Local state, backups and the audit log.	No

`skillporter.yaml`

Create it from the current workspace:

skillporter init

A fuller example:

schema_version: 2
project: acme-api
scope: project
strategy: copy
security:
  policy: HIGH
  max_risk_score: 30
harnesses:
  - claude-code
  - codex
  - cursor
skills:
  - name: pdf
    source: anthropics/skills
    ref: main
  - name: release-notes
    source: ./skills/release-notes
    harnesses: [claude-code, codex]

Top-level keys

Key	Default	Description
`schema_version`	`2`	Manifest schema version.
`project`		Project name.
`scope`	`project`	`project` or `user`.
`strategy`	`copy`	`copy` or `symlink`.
`harnesses`	`claude-code`, `codex`, `cursor`	Default harnesses for every skill.
`harness_paths`	none	Map of `harness: relative/path` overrides within the active scope.
`profile`	none	Active named environment profile.
`security.policy`	`HIGH`	Severity at or above which an install is blocked.
`security.max_risk_score`	none	Block skills whose risk score is above this value.
`security.engine`	`auto`	`auto`, `static` or `skillspector`.
`telemetry.enabled`	`false`	Opt in to the local usage log.
`skills`		The list of skills.

Skill entries

Key	Description
`name`	Skill name. It must match the skill's directory name.
`source`	Where it comes from. Any format `skillporter add` accepts.
`ref`	Git branch, tag or commit.
`version`	Version constraint.
`strategy`	Override the project strategy for this skill.
`harnesses`	Override the project harness list for this skill.
`dependencies`	Other skills this one requires.

`skillporter.lock`

Generated by skillporter sync or skillporter lock. Do not edit it by hand. See Lockfiles.

Environment variables

Variable	Purpose	Default
`HERMES_HOME`	Hermes profile home, used to resolve `$HERMES_HOME/skills`.	`~/.hermes`
`SKILLPORTER_OFFLINE`	Set to `1` to use the built-in scanner only.	unset
`SKILLPORTER_REGISTRY_URL`	Local JSON path or HTTPS URL of a custom catalog index.	built-in seed catalog
`SKILLPORTER_MCP_ROOT`	Workspace boundary for `skillporter mcp`.	working directory
`SKILLPORTER_MCP_ALLOW_WRITES`	Set to `1` to enable MCP write tools.	denied
`SKILLPORTER_MCP_ALLOW_USER_SCOPE`	Set to `1` to permit MCP `scope="user"`.	denied
`SKILLPORTER_MCP_ALLOW_REMOTE`	Set to `1` to permit remote sources for MCP `inspect` in read-only mode.	denied
`SKILLPORTER_TELEMETRY`	Set to `1` to opt in to the local usage log.	disabled
`DO_NOT_TRACK`	Set to `1` to disable telemetry regardless of other settings.	unset
`NO_COLOR`	Disable ANSI colors.	unset

The standalone installer has its own variables. See Installation.

Telemetry

Telemetry is off by default. When you opt in, events are appended to .skillporter/telemetry.jsonl inside the workspace. An event records the command, exit code, harness IDs, skill count, version and a truncated hash of the workspace path. It does not record file paths, repository URLs, usernames, environment variables or skill contents. DO_NOT_TRACK=1 disables it unconditionally.