Using AI Agent Skills with the SDK

The SDK can install provider-agnostic agent skills for common transform development workflows: transform authoring basics, SDK authoring, TRX migration, direct server discovery, official docs lookup, and local testing.

Install Skills into a New Project

Project-local install is the default when scaffolding a new project:

maltego-transforms start my_project --with-skills

This creates:

• .agents/skills with the SDK skill set.
• .agents/README.md with a short loading hint.
• AGENTS.md at the project root, pointing agents to the skill index.

Agents started in the generated project should read this file first:

.agents/skills/maltego-transform-skill-index/SKILL.md

That index routes the agent to the one focused skill needed for the current task. It is intentionally small so agents do not load every reference file at once.

Install Skills into an Existing Project

To add skills to a project that already exists — without re-scaffolding it — use the standalone install-skills command:

pip install maltego-transforms
maltego-transforms install-skills --target .

This installs the same SDK skill set into .agents/skills of the target directory, writes .agents/README.md, and appends a skills pointer to AGENTS.md. No template files or project.py are created or overwritten.

Use --target PATH to point at a directory other than the current one.

Global Install

If your agent runtime reads a shared provider-agnostic skills directory, install the skills globally so they are available from any project:

maltego-transforms start my_project --with-skills --skills-scope global

Or, for an existing environment without scaffolding:

maltego-transforms install-skills --scope global

By default the global install writes to ~/.agents/skills. Use global install when you want the Maltego SDK skills available across projects. Use local install when the skills should travel with a specific project.

Recommended Agent Workflow

For a new SDK project or migration task:

1. Start the agent in the generated project directory.
2. Read .agents/skills/maltego-transform-skill-index/SKILL.md.
3. Load the focused skill selected by the index.
4. Load referenced files only when the focused skill asks for them.

For a TRX migration, the intended flow is:

Recommended path:

1. Use maltego-trx-migration-planner to inspect the old TRX project and write an evidence-backed migration contract.
2. Use maltego-trx-migration-implementer to rewrite transforms into async SDK functions.

Optional deep dives:

• Use maltego-transform-basics when common transform mechanics need a quick reference. It is intentionally a surface-level primer, not a full SDK guide.
• Use maltego-transform-docs when installed source, tests, or generated examples do not settle an SDK API question.
• Use maltego-transform-discover when server discovery or transform IDs need deeper debugging.
• Use maltego-transform-test when transform execution, mocks, or runtime checks need more detail.

Required outcomes:

• A migration plan with source behavior evidence and SDK evidence.
• SDK-native transform code with no TRX authoring imports or wrappers.
• Runtime behavior checks for representative transforms.
• Direct SDK discovery through /api/v3/transforms that matches the source contract.
• Migration completion gates from maltego-trx-migration-implementer.
• Portable artifacts that use workspace-relative paths.

Teams can customize this flow, add their own skills, or replace the optional support skills. Keep the required outcomes so migrations remain reviewable and comparable across agent runtimes.

The migration skills target clean SDK rewrites. They do not assume classic protocol packages, MTZ discovery, iTDS/pTDS discovery, or internal Maltego infrastructure.

Prompt Example

After creating a project with --with-skills, a task can be phrased like:

Start in this generated project. Read
.agents/skills/maltego-transform-skill-index/SKILL.md, then use the TRX
migration planner and implementer skills to migrate the existing TRX server
into this SDK package.

If the agent runtime does not auto-discover local skills, that explicit pointer still gives it a deterministic first file to read.