Guidelines
akash-network/node
Behavioral guidelines to reduce common LLM coding mistakes. An agent skill from akash-network/node.
Convert a legacy handwritten-Cypher Cartography sync (load / cleanup JSON jobs) into the modern declarative data model (load(), GraphJob.fromnodeschema()).
$ npx skills add cartography-cncf/cartography --skill refactor-legacy -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install cartography-cncf/cartography refactor-legacy --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/cartography-cncf/cartography.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/refactor-legacy .claude/skills/refactor-legacy && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "refactor-legacy" agent skill from https://github.com/cartography-cncf/cartography/tree/master/.agents/skills/refactor-legacy into .claude/skills/refactor-legacy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "refactor-legacy", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/cartography-cncf/cartography/tree/master/.agents/skills/refactor-legacyType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add cartography-cncf/cartography --skill refactor-legacy -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install cartography-cncf/cartography refactor-legacy --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/cartography-cncf/cartography.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/refactor-legacy .agents/skills/refactor-legacy && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "refactor-legacy" agent skill from https://github.com/cartography-cncf/cartography/tree/master/.agents/skills/refactor-legacy into .agents/skills/refactor-legacy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "refactor-legacy", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add cartography-cncf/cartography --skill refactor-legacy -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install cartography-cncf/cartography refactor-legacy --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/cartography-cncf/cartography.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/refactor-legacy .cursor/skills/refactor-legacy && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "refactor-legacy" agent skill from https://github.com/cartography-cncf/cartography/tree/master/.agents/skills/refactor-legacy into .cursor/skills/refactor-legacy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "refactor-legacy", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/cartography-cncf/cartography.git --path .agents/skills/refactor-legacy--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add cartography-cncf/cartography --skill refactor-legacy -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install cartography-cncf/cartography refactor-legacy --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/cartography-cncf/cartography.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/refactor-legacy .gemini/skills/refactor-legacy && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "refactor-legacy" agent skill from https://github.com/cartography-cncf/cartography/tree/master/.agents/skills/refactor-legacy into .gemini/skills/refactor-legacy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "refactor-legacy", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install cartography-cncf/cartography refactor-legacyInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add cartography-cncf/cartography --skill refactor-legacy -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/cartography-cncf/cartography.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/refactor-legacy .github/skills/refactor-legacy && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "refactor-legacy" agent skill from https://github.com/cartography-cncf/cartography/tree/master/.agents/skills/refactor-legacy into .github/skills/refactor-legacy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "refactor-legacy", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add cartography-cncf/cartography --skill refactor-legacy -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install cartography-cncf/cartography refactor-legacy --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/cartography-cncf/cartography.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/refactor-legacy .opencode/skills/refactor-legacy && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "refactor-legacy" agent skill from https://github.com/cartography-cncf/cartography/tree/master/.agents/skills/refactor-legacy into .opencode/skills/refactor-legacy/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "refactor-legacy", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
refactor-legacyConvert a legacy handwritten-Cypher Cartography sync (load / cleanup JSON jobs) into the modern declarative data model (load(), GraphJob.fromnodeschema()).
Refactor Legacy is an agent skill from cartography-cncf/cartography. Convert a legacy handwritten-Cypher Cartography sync (load / cleanup JSON jobs) into the modern declarative data model (load(), GraphJob.fromnodeschema()). Use when the user asks to refactor, modernise, migrate, or "clean up" a legacy intel module, or to remove a cleanup/.json job tied to an old MERGE query.
Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Development, covering Refactoring. The repository describes itself as: Cartography is a Python tool that pulls infrastructure assets and their relationships into a Neo4j graph database. The licence is Apache-2.0.
3 steps, taken from the step headings in SKILL.md.
Read from SKILL.md and the folder at commit e345364. It shows what the files ask for, not the result of running them.
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Shell commands in SKILL.md call:
gitFrom the folder's file list and the shell code blocks in SKILL.md.
No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Refactor Legacy loads about 2.5k tokens when it runs. Until then it costs about 86 tokens; SKILL.md has 701 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
The full file from cartography-cncf/cartography at commit e345364, republished under its Apache-2.0 licence (© cartography-cncf). 701 words, ~2,471 tokens.
.claude/skills/refactor-legacy/SKILL.md (or your agent's skills folder).A critical task for AI agents: refactor legacy Cartography modules from handwritten Cypher to the declarative data model. The modern approach generates optimised queries automatically, improves maintainability, and removes manual index / cleanup boilerplate.
MERGE/CREATE write queries to load() with CartographyNodeSchema. Convert handwritten cleanup to GraphJob.from_node_schema().run_write_query() (managed transaction + retries). Never keep raw neo4j_session.run(...) writes during refactors.Locate the main sync_*() for the module — usually sync_ec2_instances(), sync_users(), etc.
Example: cartography.intel.aws.ec2.instances.sync().
Look in tests/integration/cartography/intel/[module]/. The test must call the sync function directly. If none exists, create one before any refactoring:
# tests/integration/cartography/intel/aws/ec2/test_instances.py
from unittest.mock import patch
import cartography.intel.aws.ec2.instances
from tests.data.aws.ec2.instances import MOCK_INSTANCES_DATA
from tests.integration.util import check_nodes, check_rels
TEST_UPDATE_TAG = 123456789
TEST_AWS_ACCOUNT_ID = "123456789012"
@patch.object(cartography.intel.aws.ec2.instances, "get", return_value=MOCK_INSTANCES_DATA)
def test_sync_ec2_instances(mock_get, neo4j_session):
cartography.intel.aws.ec2.instances.sync(
neo4j_session,
boto3_session=None, # mocked
regions=["us-east-1"],
current_aws_account_id=TEST_AWS_ACCOUNT_ID,
update_tag=TEST_UPDATE_TAG,
common_job_parameters={
"UPDATE_TAG": TEST_UPDATE_TAG,
"AWS_ID": TEST_AWS_ACCOUNT_ID,
},
)
expected_nodes = {
("i-1234567890abcdef0", "running"),
("i-0987654321fedcba0", "stopped"),
}
assert check_nodes(neo4j_session, "AWSEC2Instance", ["id", "state"]) == expected_nodesRun the test against the legacy code and ensure it passes. If it does not exist or does not pass, fix that first — no exceptions.
cartography/models/[module]/# cartography/models/aws/ec2/instances.py
from dataclasses import dataclass
from cartography.models.core.common import PropertyRef
from cartography.models.core.nodes import CartographyNodeProperties, CartographyNodeSchema
from cartography.models.core.relationships import CartographyRelSchema, LinkDirection, make_target_node_matcher
@dataclass(frozen=True)
class EC2InstanceNodeProperties(CartographyNodeProperties):
id: PropertyRef = PropertyRef("id")
lastupdated: PropertyRef = PropertyRef("lastupdated", set_in_kwargs=True)
instanceid: PropertyRef = PropertyRef("InstanceId")
state: PropertyRef = PropertyRef("State")
# ... other properties
@dataclass(frozen=True)
class EC2InstanceToAWSAccountRel(CartographyRelSchema):
target_node_label: str = "AWSAccount"
target_node_matcher: TargetNodeMatcher = make_target_node_matcher({
"id": PropertyRef("AWS_ID", set_in_kwargs=True),
})
direction: LinkDirection = LinkDirection.INWARD
rel_label: str = "RESOURCE"
properties: EC2InstanceToAWSAccountRelProperties = EC2InstanceToAWSAccountRelProperties()
@dataclass(frozen=True)
class EC2InstanceSchema(CartographyNodeSchema):
label: str = "AWSEC2Instance"
properties: EC2InstanceNodeProperties = EC2InstanceNodeProperties()
sub_resource_relationship: EC2InstanceToAWSAccountRel = EC2InstanceToAWSAccountRel()For node, relationship, and schema details, see the add-node-type and add-relationship skills.
load_* functions# Before
def load_ec2_instances(neo4j_session, data, region, current_aws_account_id, update_tag):
ingest_instances = """
UNWIND $instances_list AS instance
MERGE (i:AWSEC2Instance {id: instance.id})
ON CREATE SET i.firstseen = timestamp()
SET i.instanceid = instance.InstanceId,
i.state = instance.State,
i.lastupdated = $update_tag
WITH i
MATCH (owner:AWSAccount {id: $aws_account_id})
MERGE (owner)-[r:RESOURCE]->(i)
ON CREATE SET r.firstseen = timestamp()
SET r.lastupdated = $update_tag
"""
neo4j_session.run(ingest_instances, instances_list=data, aws_account_id=current_aws_account_id, update_tag=update_tag)
# After
def load_ec2_instances(neo4j_session, data, region, current_aws_account_id, update_tag):
load(
neo4j_session,
EC2InstanceSchema(),
data,
lastupdated=update_tag,
AWS_ID=current_aws_account_id,
)If you genuinely need a hand-written write query during the refactor, replace neo4j_session.run(...) with run_write_query() so the write benefits from Cartography's managed transaction + retry handling.
cleanup_* functions# Before
def cleanup_ec2_instances(neo4j_session, common_job_parameters):
run_cleanup_job("aws_import_ec2_instances_cleanup.json", neo4j_session, common_job_parameters)
# After
def cleanup_ec2_instances(neo4j_session, common_job_parameters):
GraphJob.from_node_schema(EC2InstanceSchema(), common_job_parameters).run(neo4j_session)After each chunk, run the integration test. Tests may need minor tweaks for property names that the data model normalises, but they should keep passing.
Once tests pass, remove the legacy bookkeeping for the nodes you converted.
In cartography/data/indexes.cypher:
# Remove entries like these — the data model creates indexes automatically
CREATE INDEX IF NOT EXISTS FOR (n:AWSEC2Instance) ON (n.id);
CREATE INDEX IF NOT EXISTS FOR (n:AWSEC2Instance) ON (n.lastupdated);Only remove indexes for nodes you actually converted.
rm cartography/data/jobs/cleanup/aws_import_ec2_instances_cleanup.jsonOnly remove cleanup files for fully-converted modules.
add-node-type skill) or composite-node patterns (add-relationship skill).add-relationship skill.(See add-relationship skill, "Multi-module patterns".)
Break them down: identify what nodes/relationships are being created, map to schemas, then use multiple load() calls if needed.
Do not explicitly test cleanup unless you have a specific concern. The data model handles complex cleanup automatically and testing it adds boilerplate. Focus tests on data ingestion outcomes.
Refactors get hairy. Stop and ask the user when:
load_* functions converted to load()cleanup_* functions converted to GraphJob.from_node_schema()indexes.cyphercartography/data/jobs/cleanup/git commit -s)A successful refactor:
See the troubleshooting skill for PropertyRef validation failed, missing relationships, cleanup misbehaviour, and related errors.
© cartography-cncf, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Just SKILL.md in .agents/skills/refactor-legacy of cartography-cncf/cartography.
Open the folder on GitHubat commit e345364
Refactor Legacy next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Refactor Legacy this skillcartography-cncf/cartography | 4.1k | — | ~2.5k | Automated safety check: Pass | Apache-2.0 | |
| Guidelinesakash-network/node | 1.1k | 20 repos | ~577 | Automated safety check: Pass | MIT | |
| Component Refactoringlangflow-ai/langflow | 155k | — | ~3.5k | Automated safety check: Pass | MIT | |
| Migrate Core Code to Submodulestinyhumansai/openhuman | 42k | — | ~2.6k | Automated safety check: Pass | GPL-3.0 | |
| ast-grep Structural Searchcode-yeongyu/oh-my-openagent | 70k | — | ~3.3k | Automated safety check: Pass | MIT | |
| Systematic Code Refactoringluongnv89/claude-howto | 42k | — | ~3k | Automated safety check: Pass | MIT |
akash-network/node
Behavioral guidelines to reduce common LLM coding mistakes. An agent skill from akash-network/node.
langflow-ai/langflow
Refactor high-complexity React components in Langflow frontend.
tinyhumansai/openhuman
Plans and carries out moving non-host-specific code and its tests from the OpenHuman core into vendored tiny submodule libraries, then releases the submodule and re-pins the host.
code-yeongyu/oh-my-openagent
Searches and rewrites code by syntax-tree shape across 25 languages with ast-grep, for codemods, structural queries and YAML lint rules, using a Python wrapper script.
luongnv89/claude-howto
Guides refactoring in phases based on Martin Fowler's method: research, test coverage check, planning and small tested steps, with your approval at each phase.
skills-directory/skill-codex
A skill your agent uses when the user asks to run Codex CLI (codex exec, codex resume) or references OpenAI Codex for code analysis, refactoring, or automated editing
cartography-cncf/cartography
Define a new node schema under cartography/models/MODULENAME/, including required properties, sub-resource relationships, extra labels, conditional labels, scoped cleanup, and one-to-many transforms.
cartography-cncf/cartography
Define a CartographyRelSchema (standard relationship), one-to-many edge, or MatchLink connecting existing nodes.
cartography-cncf/cartography
Add a post-ingestion typed analysis job to a Cartography module to enrich the graph after sync.
cartography-cncf/cartography
Author a new Cartography intel module end-to-end (entry point, sync GET/TRANSFORM/LOAD/CLEANUP, declarative data model, integration test, schema docs).
cartography-cncf/cartography
Author a Cartography security rule (one or more Cypher Facts plus a Pydantic Finding output model) under cartography/rules/data/rules/.
cartography-cncf/cartography
Map a Cartography node into the Ontology system using semantic labels (UserAccount, DeviceInstance, Tenant, Database, ObjectStorage, FileStorage) or canonical nodes (User, Device).
Categories
Convert a legacy handwritten-Cypher Cartography sync (load / cleanup JSON jobs) into the modern declarative data model (load(), GraphJob.fromnodeschema()). Refactor Legacy is an agent skill from cartography-cncf/cartography.fromnodeschema()).
Refactor Legacy fits situations like: the user asks to refactor; clean up a legacy intel module; remove a cleanup/.json job tied to an old MERGE query.
Run `npx skills add cartography-cncf/cartography --skill refactor-legacy -a claude-code`. Or copy the skill folder (.agents/skills/refactor-legacy in cartography-cncf/cartography) into .claude/skills/refactor-legacy in your project. Claude Code loads it when a task matches its description.
Run `npx skills add cartography-cncf/cartography --skill refactor-legacy -a codex`. Or copy the skill folder (.agents/skills/refactor-legacy in cartography-cncf/cartography) into .agents/skills/refactor-legacy in your project. Codex loads it when a task matches its description.
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add cartography-cncf/cartography --skill refactor-legacy -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/refactor-legacy, .gemini/skills/refactor-legacy, .github/skills/refactor-legacy and .opencode/skills/refactor-legacy in your project.
Going by SKILL.md and its folder, Refactor Legacy needs the command-line tools its instructions call (git). Our summary lists: Python 3.
SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
Refactor Legacy is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
About 2.5k tokens (SKILL.md is roughly 9.9k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
Skills that share tags, products or a category with Refactor Legacy: Guidelines (akash-network/node, 1.1k stars), Component Refactoring (langflow-ai/langflow, 155k stars), Migrate Core Code to Submodules (tinyhumansai/openhuman, 42k stars) and ast-grep Structural Search (code-yeongyu/oh-my-openagent, 70k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
cartography-cncf (a GitHub organization) maintains it in cartography-cncf/cartography, which has 4,128 GitHub stars. The repository holds 11 skills in this directory. The repository was last updated on October 9, 2026.
Source: cartography-cncf/cartography on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.