Skills give investigation actors domain expertise. A skill is a markdown document loaded into actor context — it tells the actor how to reason about a class of finding before it starts investigating. No code, no APIs, just structured knowledge.
When an investigation actor starts on a finding, it receives context: the finding itself, relevant events, tool results. Skills add a fourth piece — curated domain knowledge telling the actor what to look for and how to interpret what it finds.
A skill for privilege escalation analysis, for example, explains the difference between a grant event and an escalation, describes elevated window analysis, and gives the actor concrete patterns to flag. The actor brings reasoning; the skill brings expertise.
Skills are loaded by name. An actor's manifest.yaml declares which skills
to load, and the skill content is injected into the actor's system context before the
investigation begins.
A skill is a directory containing a SKILL.md file. The file starts with
YAML frontmatter, followed by the skill body in markdown.
mallcop
---
name: my-skill
description: "One-line summary of what this skill covers"
version: "1.0"
author: you@example.com
parent: privilege-analysis # optional: inherit from parent
tools: none # optional: tool hints
---
## Investigation Context
Write the knowledge the actor needs here. Explain:
- What patterns indicate a real finding vs. noise
- What data points to collect first
- Common false positive patterns and how to rule them out
- Thresholds and baseline interpretation guidance
| Field | Required | Description |
|---|---|---|
name | Yes | Unique identifier. Used in actor manifests and mallcop skill commands. Lowercase, hyphens allowed. |
description | Yes | One-line summary shown in mallcop trust list and skill listings. |
version | No | Semantic version string. Stored in skills.lock. |
author | No | Author identity (usually an email). Must match the signing key identity for trust verification. |
parent | No | Name of a parent skill. The parent's body is loaded before this skill's body. |
tools | No | Tool hints for the actor runtime. Currently informational. |
Three skills ship with mallcop. They load automatically when relevant actor types are invoked. Built-in skills are signed with the mallcop root key and require no trust setup.
General privilege escalation reasoning — role grants, permission changes, elevation patterns. Covers the grant/use/escalation distinction, elevated window analysis, service account vs. human patterns, and approval chain interpretation.
Loaded by: triage, investigate actors when the finding type is priv-escalation.
AWS IAM investigation — trust policies, AssumeRole chain tracing, service-linked roles, SCPs. Explains how to read trust policy principal fields, how to follow AssumeRole chains through CloudTrail, and how SCPs interact with role-level permissions.
Parent: privilege-analysis (general escalation context loaded first).
Loaded by: investigate actors on AWS findings involving IAM events.
OpenClaw/Cline agent security — malicious skill detection, MCP abuse patterns, ClawHavoc campaign indicators of compromise. Includes specific IOC patterns from the ClawHavoc corpus: delayed trigger conditions, namespace conflicts, author identity spoofing, and version creep.
Loaded by: investigate actors when the finding type is malicious-skill.
Skills can declare a parent via the parent frontmatter field. When a skill
with a parent is loaded, the parent's body is injected first, followed by the child's body.
This allows specialist skills to inherit general domain context without duplicating it.
Example: aws-iam declares parent: privilege-analysis. An actor
investigating an AWS IAM escalation gets the general privilege escalation framework first,
then the AWS-specific trust policy and AssumeRole chain guidance on top of it.
Chains can be deeper than one level. The runtime loads the full ancestor chain, outermost ancestor first.
Drop custom skills into ~/.mallcop/skills/ or into a
skills/ directory in your deployment repo.
skills/
my-skill/
SKILL.md # required: frontmatter + body
SKILL.md.sig # generated by: mallcop skill sign
Skill bodies are injected verbatim into actor context. Write for the model: clear structure, concrete patterns, specific thresholds. Avoid prose that the actor would have to interpret — be explicit about what to look for and what it means.
Good skill bodies typically include:
Keep bodies focused. A skill covering six unrelated topics is harder for the actor to apply correctly than six single-topic skills loaded selectively.
# manifest.yaml (in plugins/actors/my-actor/)
name: my-actor
type: agent
skills:
- my-skill
- privilege-analysis # can mix built-in and custom
Sign a skill directory with an SSH private key. Produces SKILL.md.sig.
mallcop skill sign DIR --key ~/.ssh/id_ed25519
The signature covers all files in the skill directory (excluding SKILL.md.sig itself).
Any change to any file — including adding or removing files — invalidates the signature.
Verify a skill directory's signature against a public key.
mallcop skill verify DIR --pubkey ~/.ssh/id_ed25519.pub mallcop skill verify DIR --pubkey key.pub --identity author@example.com
Exits 0 if the signature is valid. Exits non-zero otherwise.
The --identity flag overrides the identity taken from the pubkey comment field.
Regenerate skills.lock from the current installed skills. The lockfile records
SHA-256 hashes of every skill's content and is checked at startup in fail-closed mode.
mallcop skill lock mallcop skill lock --skills-dir ./skills --output ./skills.lock
Run this after adding, updating, or removing skills. Commit skills.lock
to your deployment repo. See Trust: skills.lock for
how hash pinning works.