Agent skill

knowledge-graph

Manages persistent Knowledge Graph for specifications. Caches agent discoveries and codebase analysis to remember findings across sessions. Validates task dependencies, stores patterns, components, and APIs to avoid redundant exploration. Use when: you need to cache analysis results, remember findings, reuse previous discoveries, look up what we found, spec-to-tasks needs to persist codebase analysis, task-implementation needs to validate contracts, or any command needs to query existing patterns/components/APIs.

View SKILL.md on GitHub Repository
Stars 192
Forks 20

Install this agent skill to your Project

npx add-skill https://github.com/giuseppe-trisciuoglio/developer-kit/tree/main/plugins/developer-kit-core/skills/knowledge-graph

SKILL.md

Knowledge Graph Skill

Overview

Persistent JSON storage that caches agent discoveries and codebase analysis. Remember findings across sessions, validate task dependencies, query patterns/components/APIs, skip redundant exploration.

Location: docs/specs/[ID-feature]/knowledge-graph.json

When to Use

  1. Cache results - Before launching expensive codebase analysis, check if findings are already stored
  2. Remember findings - After agent exploration, persist discoveries for future use
  3. Reuse discoveries - Query existing context to maintain consistency across tasks
  4. Validate dependencies - Check if required components/APIs exist before implementing
  5. Look up previous work - Find what patterns, components, or APIs were already discovered

Instructions

read-knowledge-graph

Read existing Knowledge Graph or initialize empty structure:

Read file_path="docs/specs/001/knowledge-graph.json"

Returns full KG content. If file missing, returns empty structure and creates on first update.

query-knowledge-graph

Query specific sections: components, patterns, apis, integration-points, all

Read file_path="docs/specs/001/knowledge-graph.json"

Filter results by section and process in-memory.

update-knowledge-graph

# 1. Read existing
Read file_path="docs/specs/001/knowledge-graph.json"

# 2. Deep-merge updates (arrays append by ID, objects preserve existing)
# 3. Update timestamp
Write file_path="docs/specs/001/knowledge-graph.json" content="<merged JSON>"

Deep-merge rules:

  • Arrays: append new items, deduplicate by id field
  • Objects: preserve existing keys, add/update new keys
  • Always update metadata.updated_at to current ISO timestamp

Complete JSON example for update:

json
{
  "metadata": {
    "spec_id": "001-hotel-search",
    "created_at": "2026-03-14T10:30:00Z",
    "updated_at": "2026-03-23T10:00:00Z",
    "version": "1.0.0"
  },
  "patterns": {
    "architectural": [
      {
        "id": "pat-001",
        "name": "Repository Pattern",
        "convention": "Extend JpaRepository<Entity, ID>",
        "files": ["src/main/java/**/repository/*Repository.java"]
      }
    ]
  },
  "components": {
    "services": [
      {
        "id": "comp-svc-001",
        "name": "HotelService",
        "location": "src/main/java/com/example/hotel/service/HotelService.java",
        "type": "service",
        "methods": [{"name": "searchHotels", "returns": "List<HotelDTO>"}]
      }
    ]
  }
}

validate-against-knowledge-graph

# 1. Read KG
Read file_path="docs/specs/001/knowledge-graph.json"

# 2. Check KG contains required IDs
# 3. Verify actual files exist
Grep pattern="src/**/HotelRepository.java"

Report satisfied dependencies and missing components.

validate-contract

# 1. Read KG and task expectations
Read file_path="docs/specs/001/knowledge-graph.json"
Glob pattern="src/**/ExpectedFile.java"
Grep pattern="class ExpectedClass|interface ExpectedInterface"

# 2. Match expectations against KG.provides
# 3. Report satisfied/unsatisfied contracts

extract-provides

# 1. Find implementation files
Glob pattern="src/**/*.java"

# 2. Extract symbols
Grep pattern="^(public|protected)? (class|interface|enum) " output_mode="content"

# 3. Classify by directory: /entity/ → entity, /service/ → service, /repository/ → repository
# 4. Update KG.provides with {task_id, file, symbols, type, implemented_at}

aggregate-knowledge-graphs

# 1. Find all KG files
Glob pattern="docs/specs/*/knowledge-graph.json"

# 2. Read each, extract patterns.architectural and patterns.conventions
# 3. Write merged .global-knowledge-graph.json
Write file_path="docs/specs/.global-knowledge-graph.json" content="<aggregated>"

Schema Structure

knowledge-graph.json
├── metadata (spec_id, created_at, updated_at, version, analysis_sources)
├── codebase_context (project_structure, technology_stack)
├── patterns (architectural[], conventions[])
├── components (controllers[], services[], repositories[], entities[], dtos[])
├── provides[] ({ task_id, file, symbols[], type, implemented_at })
├── apis (internal[], external[])
└── integration_points[]

Complete schema with field definitions: See references/schema.md

Error Handling

Scenario Handling
File not found Return empty KG; creates on first update
Invalid JSON Raise error; offer to recreate from analysis
Merge conflicts Deep-merge preserves existing, adds new with timestamps
Write failure Log error; continue without caching (non-blocking)

Update workflow:

  1. Read: Read → docs/specs/[ID]/knowledge-graph.json
  2. Validate update JSON structure
  3. Deep-merge updates into KG object
  4. Write: Write → same path
  5. Verify write succeeded

Best Practices

Before expensive operations:

  • Query KG first to check for cached analysis
  • If fresh (< 7 days), skip redundant exploration
  • Offer user choice: use cached or re-explore

After discoveries:

  • Update KG immediately after agent analysis completes
  • Include source agent/timestamp in metadata
  • Batch similar updates, avoid per-operation writes

Freshness guidelines:

  • < 7 days: Fresh, safe to use
  • 7-30 days: Consider regenerating

  • 30 days: Stale, re-analysis recommended

Examples

Cache Agent Discoveries (Complete Workflow)

# Step 1: Check existing KG
Read file_path="docs/specs/001/knowledge-graph.json"

# Step 2: Analyze codebase (agent task)
Glob pattern="src/main/java/**/*.java"
Grep pattern="public (class|interface) " output_mode="content"

# Step 3: Build update with discoveries
Write file_path="docs/specs/001/knowledge-graph.json" content="{
  \"metadata\": {
    \"spec_id\": \"001-hotel-search\",
    \"created_at\": \"2026-03-14T10:30:00Z\",
    \"updated_at\": \"2026-03-23T10:00:00Z\",
    \"version\": \"1.0.0\",
    \"analysis_sources\": [{\"agent\": \"general-code-explorer\", \"timestamp\": \"2026-03-23T10:00:00Z\"}]
  },
  \"patterns\": {
    \"architectural\": [{
      \"id\": \"pat-001\",
      \"name\": \"Repository Pattern\",
      \"convention\": \"Extend JpaRepository<Entity, ID>\"
    }]
  },
  \"components\": {
    \"services\": [{
      \"id\": \"comp-svc-001\",
      \"name\": \"HotelService\",
      \"location\": \"src/main/java/com/example/hotel/service/HotelService.java\",
      \"type\": \"service\"
    }],
    \"repositories\": [{
      \"id\": \"comp-repo-001\",
      \"name\": \"HotelRepository\",
      \"location\": \"src/main/java/com/example/hotel/repository/HotelRepository.java\",
      \"type\": \"repository\"
    }]
  }
}"

Validate Task Dependencies

# Read KG and task requirements
Read file_path="docs/specs/001/knowledge-graph.json"

# Verify components exist in codebase
Grep pattern="src/main/java/com/example/hotel/repository/HotelRepository.java"
Grep pattern="src/main/java/com/example/hotel/service/HotelService.java"

# Report validation result
# If all found: "All dependencies satisfied, proceed with implementation"
# If missing: "Warning: HotelService not found. Create it first?"

Query for Context Before Task Generation

# Load KG to get cached context
Read file_path="docs/specs/001/knowledge-graph.json"

# Present summary to user:
# "Found cached analysis (2 days old):
#  - Patterns: Repository Pattern, Service Layer
#  - Components: HotelService, HotelController
#  - Conventions: naming with *Controller/*Service/*Repository
#  Use cached context for task generation?"

More examples: See references/query-examples.md

Constraints and Warnings

Critical Constraints:

  • Read-only on source code; only creates/updates knowledge-graph.json
  • Only reads/writes KG files from docs/specs/[ID]/ paths
  • Does NOT generate implementation code automatically

Limitations:

  • Validation checks KG only; cannot verify actual codebase if KG outdated
  • KG accuracy depends on freshness; re-explore if > 7 days old
  • Cross-spec learning only via aggregate operation

Warnings:

  • KG > 30 days old may not reflect current codebase state
  • Validator may report false negatives if KG predates implementation
  • Merge strategy preserves existing values; explicit overwrite required to replace

See Also

  • references/schema.md - Complete JSON schema with field definitions
  • references/query-examples.md - Query patterns and integration examples
  • references/integration-patterns.md - Command integration details

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

giuseppe-trisciuoglio/developer-kit

aws-cli-beast

Provides advanced AWS CLI patterns for managing EC2, Lambda, S3, DynamoDB, RDS, VPC, IAM, and CloudWatch. Generates bulk operation scripts, automates cross-service workflows, validates security configurations, and executes JMESPath queries for complex filtering. Triggers on "aws cli help", "aws command line", "aws scripting", "aws automation", "aws batch operations", "aws bulk operations", "aws cli pagination", "aws multi-region", "aws profiles", "aws cli troubleshooting".

192 20
Explore
giuseppe-trisciuoglio/developer-kit

aws-cost-optimization

Provides structured AWS cost optimization guidance using five pillars (right-sizing, elasticity, pricing models, storage optimization, monitoring) and twelve actionable best practices with executable AWS CLI examples. Use when optimizing AWS costs, reviewing AWS spending, finding unused AWS resources, implementing FinOps practices, reducing EC2/EBS/S3 bills, configuring AWS Budgets, or performing AWS Well-Architected cost reviews.

192 20
Explore
giuseppe-trisciuoglio/developer-kit

aws-sam-bootstrap

Provides AWS SAM bootstrap patterns: generates `template.yaml` and `samconfig.toml` for new projects via `sam init`, creates SAM templates for existing Lambda/CloudFormation code migration, validates build/package/deploy workflows, and configures local testing with `sam local invoke`. Use when the user asks about SAM projects, `sam init`, `sam deploy`, serverless deployments, or needs to bootstrap/migrate Lambda functions with SAM templates.

192 20
Explore
giuseppe-trisciuoglio/developer-kit

aws-drawio-architecture-diagrams

Creates professional AWS architecture diagrams in draw.io XML format (.drawio files) using official AWS Architecture Icons (aws4 library). Use when the user asks for AWS diagrams, VPC layouts, multi-tier architectures, serverless designs, network topology, or draw.io exports involving Lambda, EC2, RDS, or other AWS services.

192 20
Explore
giuseppe-trisciuoglio/developer-kit

aws-cloudformation-bedrock

Provides AWS CloudFormation patterns for Amazon Bedrock resources including agents, knowledge bases, data sources, guardrails, prompts, flows, and inference profiles. Use when creating Bedrock agents with action groups, implementing RAG with knowledge bases, configuring vector stores, setting up content moderation guardrails, managing prompts, orchestrating workflows with flows, and configuring inference profiles for model optimization.

192 20
Explore
giuseppe-trisciuoglio/developer-kit

aws-cloudformation-s3

Provides AWS CloudFormation patterns for Amazon S3. Use when creating S3 buckets, policies, versioning, lifecycle rules, and implementing template structure with Parameters, Outputs, Mappings, Conditions, and cross-stack references.

192 20
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results