Scaffold Investigation Skill

scaffold-investigation-skill

A specialized skill-creator for building investigation-* skills.

Prerequisite

This skill builds on skill-creator. Install the complete skill-creator directory from that exact location. Before doing anything else, load and follow skill-creator for the base creation and revision flow — this skill adds the investigation-specific questions (tables, queries, signals, false positives, and gotchas) on top.

Purpose

Investigation skills capture how an analyst investigates one abuse domain — the tables they query, the queries they already trust, the signals they look for, and the quirks of their environment. This skill interviews you and assembles that knowledge into a consistent, spec-compliant skill so every investigation skill on your team looks and works the same way.

You bring the domain knowledge. This skill handles the structure.

When to use

Use this when you want a new investigation-{domain} skill for:

• A new abuse category not yet covered by an existing skill
• A product area with its own investigation needs
• A new data source that needs documented query patterns
• Updating an existing investigation skill with new queries, signals, gotchas, false positives, or corrections learned from real use

Don't use this for:

• General skill creation → use the base skill-creator
• Non-investigation skills (dashboards, tooling, one-off scripts)

The investigation-skill pattern

Every investigation-{domain} skill follows the same layout:

investigation-{domain}/
├── SKILL.md          # Overview, when-to-use, data sources, signals, patterns
└── references/       # Optional, loaded on demand
    ├── tables.md     # Schema, partitions, retention, gotchas
    ├── queries.md    # Full query library
    └── patterns.md   # Abuse patterns and investigation workflows

Naming convention

• Use the investigation-{domain} format (e.g. investigation-signup, investigation-billing).
• The investigation- prefix signals to the agent — and to campaign-identification — that the skill provides investigation capabilities it can orchestrate.

Recommended SKILL.md sections

1. Purpose — what domain, what you can do with it
2. When to use — the triggers that should load this skill
3. Data sources — tables/sources, how to reach them, retention, partitions
4. Key signals — abuse indicators, ideally with a rough severity
5. False positives — how to tell abuse from legitimate use
6. Common patterns — the investigation workflows you actually run
7. Output shape — what a finished result should contain (see below)
8. Related skills — cross-references to complementary skills

What the assistant collects

Work statelessly: each turn, check what's still missing and ask for the single most important gap — not everything at once.

Required before generating

Optional, but improves quality

Ready to generate when: the domain is clear, at least one source is documented, there's at least one query or a concrete description of what to find, and the basic abuse signals are named.

Output shape (bake this into every skill)

Every investigation skill should produce results a human can spot-check. Instruct the generated skill to return the minimum identifiable context needed to confirm the cluster by hand:

• A stable identifier (account id, username, or equivalent)
• Human-readable context needed for validation (created-at, country, etc.)
• The specific field that ties each row to the cluster — the connecting signal

Include email or other PII only when it is necessary for validation and the output location is approved for that data.

A finding you can't spot-check isn't actionable. Make that non-negotiable in the skills you generate.

agentskills.io spec compliance

New skills must satisfy the Agent Skills spec:

Validate before writing the file. You can ask the agent to check it:

Validate my new investigation-{domain} skill against the agentskills.io spec:
name, description, line count, and directory match.

If SKILL.md runs long, move query libraries and schema notes into references/.

Example prompts

Start interactively

Help me create a ___ investigation skill

Provide tables and queries upfront

Help me create an investigation skill for account takeovers.

Sources I use:
- recent_logins, password_change_events, email_change_events

Queries I have:
[paste your queries]

Things to know:
- A password reset followed by an email change within minutes is the strongest signal.

Scaffold from existing queries

Here are the queries I use for takeover investigations:
[paste queries]

Turn these into a proper investigation-account-takeover skill,
and ask me for any context you still need.

Add domain knowledge later

Update my investigation-account-takeover skill with this gotcha:
"last_login is updated lazily — it can lag real activity by up to an hour."

Review the existing skill, make the change in the right section, and validate
the updated skill against the agentskills.io spec.

Quality checklist

Structure

• name matches the directory name exactly
• name ≤ 64 chars, lowercase + hyphens only
• description ≤ 1024 chars and says what and when
• SKILL.md ≤ 500 lines (detail moved to references/)
• Recommended sections present

Content

• Data sources note how to reach them, retention, and partitions
• Signals named, with a rough sense of strength/severity
• False positives documented
• At least one real investigation pattern
• A handful of ready-to-run queries (in references/ if long)
• Output shape requires the minimum context needed for spot-checking
• Email and other PII are included only when necessary and appropriate

Integration

• Related-skills section cross-references complementary skills
• Skill can be picked up and orchestrated by campaign-identification

Validation

• Every documented source/column actually exists
• Every query runs before it ships
• A teammate could follow the skill and reproduce a result

Related skills

• campaign-identification — orchestrates investigation skills to expand seeds into a full campaign
• investigation-seo-spam — a worked example of the investigation-skill pattern that needs no internal data

For general guidance on tailoring skills to your own environment, see adapting-to-your-environment.md and best-practices.md.