Agent Skills: graph-skill-factory

What this skill does

Takes a variant definition (a YAML file describing the "lens" through which a codebase is documented) and generates a complete 3-file knowledge-graph-style skill. The pipeline skeleton is invariant -- the 6-step iterative process, journal-based state, one-agent-one-node principle, and wave execution pattern are the same across all variants. What varies is captured in 7 dimensions: vocabulary, taxonomy, discovery, scope, investigation, document structure, and quality criteria.

The output is a fully functional skill at ~/.claude/skills/{skill_name}/ that can be invoked immediately via /{skill_name} setup.

Invocation

• /graph-skill-factory path/to/variant.yaml -- Generate a skill from an existing variant definition file.
• /graph-skill-factory interactive -- Walk through the schema dimension by dimension, building the variant definition interactively. Writes the YAML to a file, then generates.
• /graph-skill-factory example -- Display example variant definitions for common use cases (architecture, compliance, API, threat model).

Process

Step 1: Read and validate the variant definition

Read the variant definition YAML file. Read ${CLAUDE_SKILL_DIR}/schema.md to understand required fields.

Validate:

• All 7 top-level dimensions present (vocabulary, taxonomy, discovery, scope, investigation, document_structure, quality)
• All required fields within each dimension have values
• taxonomy.fields has at least one field beyond the implicit custom and notes
• investigation.steps has at least one step
• document_structure.sections has at least one section with always_present: true
• quality.principles includes at least 3 variant-specific principles (beyond the invariant ones)
• quality.pitfalls has at least 4 entries

If validation fails, report which fields are missing and stop. If in interactive mode, prompt the user to fill them in.

Step 2: Generate the three output files

Read the assembly guides from ${CLAUDE_SKILL_DIR}/assembly/. For each output file:

1. SKILL.md -- Read ${CLAUDE_SKILL_DIR}/assembly/skill-md.md. Follow it section by section, interpolating values from the variant definition where marked with «field.path» and preserving invariant text verbatim.

2. pipeline.md -- Read ${CLAUDE_SKILL_DIR}/assembly/pipeline-md.md. Same approach. This is the largest file -- the taxonomy section and content design section are substantial.

3. Spec file ({vocabulary.spec_file}) -- Read ${CLAUDE_SKILL_DIR}/assembly/spec-md.md. This follows the /prompting skill's structure. The assembled prompt is the most complex section -- it combines multiple schema dimensions into a single coherent agent prompt.

Critical rule: {curly_braces} in the output are runtime variables for the generated skill's prompt templates -- they must be preserved literally. Only «guillemets» are template slots to be replaced during generation.

Step 3: Write to skill directory

Create ~/.claude/skills/«vocabulary.skill_name»/ and write:

• SKILL.md
• pipeline.md
• «vocabulary.spec_file»

Step 4: Verify

Run these checks on the generated files:

1. Stale terminology -- Grep for terms from known other variants that should NOT appear:

   • If the variant is not a user-manual skill: grep for \bfeature\.md\b, \bmanual\.md\b, \broles:\b (in frontmatter context)
   • If the variant is not an architecture skill: grep for \bcomponent\.md\b, \bdesign\.md\b, \bdata_classification\b
   • General: grep for knowledge-graph (should only appear if that's actually the skill name)

2. Frontmatter consistency -- Check that taxonomy field keys in the skeleton frontmatter example match the fields listed in the pipeline.md taxonomy section.

3. Section name consistency -- Check that H2 heading names in the content design section match the section names in the spec file's output contracts.

4. Variable consistency -- Check that {variable_name} placeholders in the spec file's assembled prompt match the variable list in the Step 4 orchestration section of both SKILL.md and pipeline.md.

5. Coherence read -- Read the generated SKILL.md from top to bottom and verify it reads as a coherent document, not a stitched template.

Report any issues found. Fix them before finishing.

Interactive mode

When invoked with interactive:

1. Explain what the factory does and what the 7 dimensions are.
2. Walk through each dimension in order, asking the user to describe their variant:
   • Vocabulary: "What are you documenting? What do you call each node? What's the deep-write document?"
   • Taxonomy: "What metadata should be tracked on each node? What structured fields enable filtering?"
   • Discovery: "During setup, what should the agent look for in the codebase?"
   • Scope: "What constitutes a node? What's too granular?"
   • Investigation: "What should the Step 4 agents investigate? In what order?"
   • Document structure: "What sections should the deep-write document have? Who's the audience for each?"
   • Quality: "What are the key invariants? What are the common pitfalls?"
3. After each dimension, write the YAML block and confirm with the user.
4. Once all 7 dimensions are captured, write the full YAML to a file.
5. Run the normal generation pipeline (steps 1-4).

Example variant ideas

These demonstrate the range of skills the factory can produce:

| Variant | Nodes | Deep doc | Lens | |---------|-------|----------|------| | User manual | features | manual (role-aware) | Who can access it, how to use it | | Architecture | components | design doc (concern-based) | How it's built, secured, operated | | Compliance | domains | assessment | Requirements → controls → evidence | | API surface | resources | reference | Contract, auth, error handling | | Threat model | surfaces | assessment | Attack surface, mitigations, residual risk | | Data lineage | entities | profile | Sources, transformations, storage, privacy | | Onboarding | areas | guide | How to work with this code area |