Extend Knowledge

Extend Factory knowledge, skills, and templates via research, documents, or user links

Extend Knowledge Skill

Extend the Factory's knowledge base, skills, and templates through multiple research methods:

•Web Search: Use web_search tool to find current information
•Document Reading: Read files, PDFs, or code repositories
•User Links: Process URLs provided by users in chat
•Synthesis: Combine sources into structured Factory artifacts

Extend Knowledge Skill

Extend the Factory's knowledge base, skills, and templates through multiple research methods:

•Web Search: Use web_search tool to find current information
•Document Reading: Read files, PDFs, or code repositories
•User Links: Process URLs provided by users in chat
•Synthesis: Combine sources into structured Factory artifacts

Artifacts Used

Artifact	Path	Purpose
Knowledge Template	`templates/knowledge/knowledge-file.tmpl`	JSON structure for knowledge
Skill Template	`templates/factory/skill.md.tmpl`	Markdown structure for skills
Agent Template	`templates/factory/agent.md.tmpl`	Markdown structure for agents
Schema	`patterns/knowledge/knowledge-schema.json`	Validation rules
Taxonomy	`scripts/taxonomy/agent_taxonomy.json`	Topic definitions

Research Methods

Method 1: Web Search Research

Use when: Topic needs current, online information

Tool: web_search

code

Step 1: web_search("{{topic}} best practices patterns 2026")
Step 2: web_search("{{topic}} implementation examples")
Step 3: web_search("{{topic}} common pitfalls anti-patterns")

What I Do:

•Execute web searches for the topic
•Read and synthesize results
•Extract patterns, examples, best practices
•Cite sources in the knowledge file

Method 2: Document Reading

Use when: User has existing docs, code, or files to incorporate

Tool: read_file

code

Step 1: read_file("{{path_to_document}}")
Step 2: Extract key patterns and concepts
Step 3: Transform into structured knowledge

Supported Formats:

•Markdown files (.md)
•JSON files (.json)
•Python/TypeScript code (extract patterns)
•YAML configuration files
•Text documentation

Method 3: User-Provided Links

Use when: User shares URLs in chat

Process:

•User provides URL: "Add knowledge from https://example.com/article"
•I use web_search with site-specific query: web_search("site:example.com {{topic}}")
•Synthesize findings into knowledge structure
•Cite the source URL

Example:

code

User: Extend knowledge using https://docs.anthropic.com/constitutional-ai

Agent: I'll research Constitutional AI from Anthropic's docs...
[web_search("site:docs.anthropic.com constitutional AI principles")]
[Synthesizes findings]
[Creates knowledge/constitutional-ai-patterns.json]

Method 4: Repository Analysis

Use when: Learning from code repositories

Tools: list_dir, read_file, grep

code

Step 1: list_dir("{{repo_path}}") - Understand structure
Step 2: grep("pattern|implementation", "{{repo_path}}") - Find key code
Step 3: read_file("{{interesting_files}}") - Analyze implementation
Step 4: Synthesize patterns into knowledge

code

Step 1: web_search("{{topic}} best practices patterns 2026")
Step 2: web_search("{{topic}} implementation examples")
Step 3: web_search("{{topic}} common pitfalls anti-patterns")

code

Step 1: read_file("{{path_to_document}}")
Step 2: Extract key patterns and concepts
Step 3: Transform into structured knowledge

code

User: Extend knowledge using https://docs.anthropic.com/constitutional-ai

Agent: I'll research Constitutional AI from Anthropic's docs...
[web_search("site:docs.anthropic.com constitutional AI principles")]
[Synthesizes findings]
[Creates knowledge/constitutional-ai-patterns.json]

code

Step 1: list_dir("{{repo_path}}") - Understand structure
Step 2: grep("pattern|implementation", "{{repo_path}}") - Find key code
Step 3: read_file("{{interesting_files}}") - Analyze implementation
Step 4: Synthesize patterns into knowledge

Extension Procedures

Procedure A: Create Knowledge File

Trigger: "Extend knowledge for {{topic}}", "Add knowledge about {{topic}}"

Steps:

•

Check Existing Knowledge

code

list_dir("knowledge")
→ See what already exists

•

Read Taxonomy

code

read_file("scripts/taxonomy/agent_taxonomy.json")
→ Understand topic requirements (depth, keywords)

•

Read Template

code

read_file("templates/knowledge/knowledge-file.tmpl")
→ Get JSON structure to follow

•

Read Schema

code

read_file("patterns/knowledge/knowledge-schema.json")
→ Get validation rules (min 3 patterns)

•

Research Topic (one or more methods)

code

web_search("{{topic}} best practices 2026")
web_search("{{topic}} implementation patterns")
read_file("{{user_provided_doc}}") if provided

•
Generate Content
- •Synthesize research into JSON structure
- •Include at least 3 patterns
- •Add code examples
- •Cite sources

•

Write File

code

write("knowledge/{{topic-name}}-patterns.json", content)

•

Validate

code

read_file("knowledge/{{topic-name}}-patterns.json")
→ Verify JSON is valid

Output: knowledge/{topic}-patterns.json (50-200 lines)

Procedure B: Create New Skill

Trigger: "Create skill for {{purpose}}", "Add a skill that {{does_what}}"

Steps:

•

Check Existing Skills

code

list_dir(".cursor/skills")
→ See what already exists, avoid duplicates

•

Read Skill Template

code

read_file("templates/factory/skill.md.tmpl")
→ Get markdown structure

•

Read Example Skill (for reference)

code

read_file(".cursor/skills/extend-knowledge/SKILL.md")
→ See good skill structure

•

Research if Needed

code

web_search("{{purpose}} workflow best practices")

•
Generate Skill Content
- •Fill template placeholders
- •Define clear process steps
- •Include tool usage examples
- •Add fallback procedures

•

Create Skill Directory

code

write(".cursor/skills/{{skill-name}}/SKILL.md", content)

Output: .cursor/skills/{skill-name}/SKILL.md

Skill Template Structure:

markdown

---
name: {{skill-name}}
description: {{what it does}}
type: skill
agents: [{{which agents use it}}]
templates: [{{templates used}}]
knowledge: [{{knowledge referenced}}]
---

# {{Skill Title}}

list_dir("knowledge") → See what already exists

code

read_file("scripts/taxonomy/agent_taxonomy.json") → Understand topic requirements (depth, keywords)

code

read_file("templates/knowledge/knowledge-file.tmpl") → Get JSON structure to follow

code

read_file("patterns/knowledge/knowledge-schema.json") → Get validation rules (min 3 patterns)

code

web_search("{{topic}} best practices 2026") web_search("{{topic}} implementation patterns") read_file("{{user_provided_doc}}") if provided

code

write("knowledge/{{topic-name}}-patterns.json", content)

code

read_file("knowledge/{{topic-name}}-patterns.json") → Verify JSON is valid

code

list_dir(".cursor/skills") → See what already exists, avoid duplicates

code

read_file("templates/factory/skill.md.tmpl") → Get markdown structure

code

read_file(".cursor/skills/extend-knowledge/SKILL.md") → See good skill structure

code

web_search("{{purpose}} workflow best practices")

code

write(".cursor/skills/{{skill-name}}/SKILL.md", content)

code


## Process
### Step 1: {{action}}
### Step 2: {{action}}

## What Gets Created/Changed
| Action | File | Change |

## Fallback Procedures
| Issue | Resolution |

Procedure C: Create New Template

Trigger: "Create template for {{purpose}}", "Add a {{type}} template"

Steps:

•

Determine Template Category

code

list_dir("templates")
→ Find appropriate category folder

•

Read Similar Template (for style)

code

read_file("templates/{{category}}/{{similar}}.tmpl")
→ Understand existing conventions

•
Design Template
- •Identify placeholders needed ({{VARIABLE_NAME}})
- •Structure for target file type
- •Include helpful comments

•

Write Template

code

write("templates/{{category}}/{{name}}.tmpl", content)

Output: templates/{category}/{name}.tmpl

Template Conventions:

•Use {{VARIABLE_NAME}} for placeholders
•Use {# comment #} for template comments
•Include header documenting all variables

Procedure D: Create New Agent

Trigger: "Create agent for {{purpose}}", "Add an agent that {{does_what}}"

Steps:

•

Check Existing Agents

code

list_dir(".cursor/agents")
→ See what already exists

•

Read Agent Template

code

read_file("templates/factory/agent.md.tmpl")
→ Get markdown structure

•

Read Example Agent (for reference)

code

read_file(".cursor/agents/knowledge-extender.md")
→ See good agent structure

•
Generate Agent Content
- •Define clear activation triggers
- •List capabilities
- •Document workflow
- •Reference skills used

•

Write Agent

code

write(".cursor/agents/{{agent-name}}.md", content)

Output: .cursor/agents/{agent-name}.md

Procedure E: Extend Existing Knowledge (Shallow Gap)

Trigger: "Improve knowledge about {{topic}}", "Add more to {{topic}}"

Steps:

•

Read Existing File

code

read_file("knowledge/{{topic}}-patterns.json")
→ Understand current content

•
Identify Gaps
- •Missing patterns?
- •Lacking code examples?
- •No best practices?

•

Research Missing Content

code

web_search("{{topic}} advanced patterns")

•

Update File

code

search_replace or write with merged content

Output: Updated knowledge/{topic}-patterns.json

code

---

### Procedure C: Create New Template

**Trigger**: "Create template for {{purpose}}", "Add a {{type}} template"

**Steps**:

1. **Determine Template Category**

code

2. **Read Similar Template** (for style)

code

3. **Design Template**
   - Identify placeholders needed (`{{VARIABLE_NAME}}`)
   - Structure for target file type
   - Include helpful comments

4. **Write Template**

code

**Output**: `templates/{category}/{name}.tmpl`

**Template Conventions**:
- Use `{{VARIABLE_NAME}}` for placeholders
- Use `{# comment #}` for template comments
- Include header documenting all variables

---

### Procedure D: Create New Agent

**Trigger**: "Create agent for {{purpose}}", "Add an agent that {{does_what}}"

**Steps**:

1. **Check Existing Agents**

code

2. **Read Agent Template**

code

3. **Read Example Agent** (for reference)

code

4. **Generate Agent Content**
   - Define clear activation triggers
   - List capabilities
   - Document workflow
   - Reference skills used

5. **Write Agent**

code

**Output**: `.cursor/agents/{agent-name}.md`

---

### Procedure E: Extend Existing Knowledge (Shallow Gap)

**Trigger**: "Improve knowledge about {{topic}}", "Add more to {{topic}}"

**Steps**:

1. **Read Existing File**

code

2. **Identify Gaps**
   - Missing patterns?
   - Lacking code examples?
   - No best practices?

3. **Research Missing Content**

code

4. **Update File**

Chat Examples

Example 1: Web Search Extension

code

User: Extend knowledge for OpenAI Agents SDK

Agent: I'll research OpenAI Agents SDK and create a knowledge file.

[list_dir("knowledge")] → No existing file
[read_file("templates/knowledge/knowledge-file.tmpl")]
[web_search("OpenAI Agents SDK patterns 2026")]
[web_search("OpenAI Agents SDK implementation examples")]
[Synthesizes findings]
[write("knowledge/openai-agents-sdk-patterns.json", ...)]

Created: knowledge/openai-agents-sdk-patterns.json
- 5 patterns added
- Code examples included
- Sources: OpenAI documentation, community best practices

Would you like me to add this to a blueprint?

Example 2: User-Provided Link

code

User: Add knowledge from this article: https://langchain.dev/docs/agents

Agent: I'll incorporate knowledge from the LangChain agents documentation.

[web_search("site:langchain.dev agents patterns implementation")]
[Synthesizes findings]
[read_file("knowledge/langchain-patterns.json")] → Exists, will extend
[Updates existing file with new patterns]

Updated: knowledge/langchain-patterns.json
- Added 3 new patterns from langchain.dev
- Added agent types section
- Cited source: https://langchain.dev/docs/agents

Example 3: Create New Skill

code

User: Create a skill for prompt testing

Agent: I'll create a skill for systematic prompt testing.

[list_dir(".cursor/skills")] → No prompt-testing skill
[read_file("templates/factory/skill.md.tmpl")]
[read_file(".cursor/skills/extend-knowledge/SKILL.md")] → Reference
[Designs skill structure]
[write(".cursor/skills/prompt-testing/SKILL.md", ...)]

Created: .cursor/skills/prompt-testing/SKILL.md

Skill includes:
- When to use: Testing prompts before deployment
- Process: Define test cases → Run variations → Analyze results
- Tools: Test matrix template, evaluation criteria

Would you like to add this skill to an agent?

Example 4: Document Incorporation

code

User: Add knowledge from docs/research/CONSTITUTIONAL_AI.md

Agent: I'll incorporate the constitutional AI research document.

[read_file("docs/research/CONSTITUTIONAL_AI.md")]
[Extracts key patterns and concepts]
[read_file("templates/knowledge/knowledge-file.tmpl")]
[Structures into knowledge format]
[write("knowledge/constitutional-ai-patterns.json", ...)]

Created: knowledge/constitutional-ai-patterns.json
- Sourced from: docs/research/CONSTITUTIONAL_AI.md
- 4 patterns extracted
- Best practices included

code

User: Extend knowledge for OpenAI Agents SDK

Agent: I'll research OpenAI Agents SDK and create a knowledge file.

[list_dir("knowledge")] → No existing file
[read_file("templates/knowledge/knowledge-file.tmpl")]
[web_search("OpenAI Agents SDK patterns 2026")]
[web_search("OpenAI Agents SDK implementation examples")]
[Synthesizes findings]
[write("knowledge/openai-agents-sdk-patterns.json", ...)]

Created: knowledge/openai-agents-sdk-patterns.json
- 5 patterns added
- Code examples included
- Sources: OpenAI documentation, community best practices

Would you like me to add this to a blueprint?

code

User: Add knowledge from this article: https://langchain.dev/docs/agents

Agent: I'll incorporate knowledge from the LangChain agents documentation.

[web_search("site:langchain.dev agents patterns implementation")]
[Synthesizes findings]
[read_file("knowledge/langchain-patterns.json")] → Exists, will extend
[Updates existing file with new patterns]

Updated: knowledge/langchain-patterns.json
- Added 3 new patterns from langchain.dev
- Added agent types section
- Cited source: https://langchain.dev/docs/agents

code

User: Create a skill for prompt testing

Agent: I'll create a skill for systematic prompt testing.

[list_dir(".cursor/skills")] → No prompt-testing skill
[read_file("templates/factory/skill.md.tmpl")]
[read_file(".cursor/skills/extend-knowledge/SKILL.md")] → Reference
[Designs skill structure]
[write(".cursor/skills/prompt-testing/SKILL.md", ...)]

Created: .cursor/skills/prompt-testing/SKILL.md

Skill includes:
- When to use: Testing prompts before deployment
- Process: Define test cases → Run variations → Analyze results
- Tools: Test matrix template, evaluation criteria

Would you like to add this skill to an agent?

code

User: Add knowledge from docs/research/CONSTITUTIONAL_AI.md

Agent: I'll incorporate the constitutional AI research document.

[read_file("docs/research/CONSTITUTIONAL_AI.md")]
[Extracts key patterns and concepts]
[read_file("templates/knowledge/knowledge-file.tmpl")]
[Structures into knowledge format]
[write("knowledge/constitutional-ai-patterns.json", ...)]

Created: knowledge/constitutional-ai-patterns.json
- Sourced from: docs/research/CONSTITUTIONAL_AI.md
- 4 patterns extracted
- Best practices included

Summary: What Gets Created

Extension Type	Output Location	Format
Knowledge	`knowledge/{topic}-patterns.json`	JSON
Skill	`.cursor/skills/{name}/SKILL.md`	Markdown
Agent	`.cursor/agents/{name}.md`	Markdown
Template	`templates/{category}/{name}.tmpl`	Template

Post-Extension Automation (MANDATORY)

Excellence Standard: Every extension MUST complete ALL post-extension steps. This is not optional.

Step 0: Determine What to Update

Read the dependency map:

code

read_file("knowledge/artifact-dependencies.json")

Detection by artifact type:

If I Created/Modified	Must Update
`knowledge/*.json` (new)	manifest.json (add entry + stats), KNOWLEDGE_FILES.md (table + count + details), CHANGELOG.md
`knowledge/*.json` (extend)	manifest.json (bump version + change_history), KNOWLEDGE_FILES.md (if description changed), CHANGELOG.md
`.cursor/skills/*/SKILL.md` (any)	skill-catalog.json, CHANGELOG.md
`.cursor/skills/*/SKILL.md` (Factory skill)	skill-catalog.json, FACTORY_COMPONENTS.md (table + details + diagram), CHANGELOG.md
`.cursor/agents/*.md` (any)	CHANGELOG.md
`.cursor/agents/*.md` (Factory agent)	FACTORY_COMPONENTS.md (table + details + diagram + integration points), CHANGELOG.md
`templates/*.tmpl`	CHANGELOG.md, (TEMPLATES.md if major)
`blueprints/*/blueprint.json`	BLUEPRINTS.md (table + details), CHANGELOG.md

Is it a Factory component? Check knowledge/artifact-dependencies.json → factory_artifact_detection:

•Factory agents: requirements-architect, stack-builder, knowledge-extender, etc.
•Factory skills: extend-knowledge, requirements-gathering, update-knowledge, etc.
•If in list → MUST update docs/reference/FACTORY_COMPONENTS.md

Find additional references:

code

grep("{{artifact_name}}", "knowledge", output_mode="files_with_matches")
grep("{{artifact_name}}", "docs", output_mode="files_with_matches")
grep("{{artifact_name}}", "blueprints", output_mode="files_with_matches")
grep("{{artifact_name}}", ".cursor", output_mode="files_with_matches")

After creating or extending ANY artifact, ALWAYS execute these steps in order:

Step 1: Update Manifest (Knowledge Files Only)

code

read_file("knowledge/manifest.json")
→ Find entry for the file (or add new entry)
→ Bump version (1.0.0 → 1.1.0 for additions, 1.0.0 → 1.0.1 for fixes)
→ Update timestamp
→ Add change_history entry

search_replace("knowledge/manifest.json", ...)

Required Fields:

json

{
  "version": "1.1.0",  // BUMP THIS
  "metadata": {
    "updated": "{{CURRENT_DATETIME}}"  // UPDATE THIS
  },
  "change_history": [  // ADD THIS
    {
      "version": "1.1.0",
      "date": "{{CURRENT_DATE}}",
      "changes": ["Added X", "Added Y"]
    }
  ]
}

Step 2: Update Skill Catalog (New Skills Only)

code

read_file("knowledge/skill-catalog.json")
→ Add entry in "skills" section
→ Add to category list at bottom

search_replace("knowledge/skill-catalog.json", ...)

Required Entry:

json

"{{skill-id}}": {
  "id": "{{skill-id}}",
  "name": "{{Skill Name}}",
  "category": "{{category}}",
  "stackAgnostic": true,
  "description": "{{description}}",
  "factorySkill": ".cursor/skills/{{skill-id}}/SKILL.md",
  "whenToUse": ["{{condition1}}", "{{condition2}}"]
}

Step 3: Update Documentation

code

read_file("docs/reference/KNOWLEDGE_FILES.md")
→ Update table entry for modified knowledge file
→ Update detailed description section

search_replace("docs/reference/KNOWLEDGE_FILES.md", ...)

For Knowledge Files: Update both the table row AND the detailed description.

Step 4: Update Changelog

code

read_file("CHANGELOG.md")
→ Add new version entry at top (after header)

search_replace("CHANGELOG.md", ...)

Required Format:

markdown

read_file("knowledge/artifact-dependencies.json")

code

grep("{{artifact_name}}", "knowledge", output_mode="files_with_matches") grep("{{artifact_name}}", "docs", output_mode="files_with_matches") grep("{{artifact_name}}", "blueprints", output_mode="files_with_matches") grep("{{artifact_name}}", ".cursor", output_mode="files_with_matches")

code

read_file("knowledge/manifest.json") → Find entry for the file (or add new entry) → Bump version (1.0.0 → 1.1.0 for additions, 1.0.0 → 1.0.1 for fixes) → Update timestamp → Add change_history entry

search_replace("knowledge/manifest.json", ...)

code


```json
{
  "version": "1.1.0",  // BUMP THIS
  "metadata": {
    "updated": "{{CURRENT_DATETIME}}"  // UPDATE THIS
  },
  "change_history": [  // ADD THIS
    {
      "version": "1.1.0",
      "date": "{{CURRENT_DATE}}",
      "changes": ["Added X", "Added Y"]
    }
  ]
}

code

read_file("knowledge/skill-catalog.json")
→ Add entry in "skills" section
→ Add to category list at bottom

search_replace("knowledge/skill-catalog.json", ...)

json

"{{skill-id}}": {
  "id": "{{skill-id}}",
  "name": "{{Skill Name}}",
  "category": "{{category}}",
  "stackAgnostic": true,
  "description": "{{description}}",
  "factorySkill": ".cursor/skills/{{skill-id}}/SKILL.md",
  "whenToUse": ["{{condition1}}", "{{condition2}}"]
}

code

read_file("docs/reference/KNOWLEDGE_FILES.md")
→ Update table entry for modified knowledge file
→ Update detailed description section

search_replace("docs/reference/KNOWLEDGE_FILES.md", ...)

code

read_file("CHANGELOG.md")
→ Add new version entry at top (after header)

search_replace("CHANGELOG.md", ...)

[X.Y.Z] - YYYY-MM-DD

Added - {{Extension Title}}

Changes

File	Action	Description
`path/to/file`	Extended/Created	What was done

code


### Step 5: Validate JSON Files

```python
# Run after all edits:
python -c "import json; json.load(open('knowledge/{{file}}.json', encoding='utf-8')); print('Valid!')"

Step 6: Git Operations (Ask User First)

ALWAYS ask before git operations:

code

⚠️ Ready to commit and push:

Modified: [list files]
New: [list files]

Proposed commit: feat(knowledge): {{description}}

Proceed? (yes/no/commit only)

code

### Step 5: Validate JSON Files

code

### Step 6: Git Operations (Ask User First)

**ALWAYS ask before git operations**:

Validation Checklist

Knowledge Files

• Valid JSON syntax
• Has $schema, title, description, version
• Has at least 3 patterns (per schema)
• Patterns have name, description, category, when_to_use
• Code examples included
• Sources cited
• Manifest updated with new version
• Documentation updated
• Changelog entry added

Skills

• Valid YAML frontmatter
• Has name, description, type: skill
• Defines When to Use
• Has clear Process steps
• Includes Fallback Procedures
• Registered in skill-catalog.json
• Changelog entry added

Agents

Best Practices

•Verify sources before synthesis: Always check that web search results are from reputable sources (official docs, established frameworks, recognized experts) before incorporating into knowledge files
•Maintain citation integrity: Include source URLs, dates, and attribution in knowledge files so future users can verify and update information
•Validate against schema early: Check knowledge files against knowledge-schema.json during creation, not after, to catch structural issues immediately
•Use multiple research methods: Combine web search, document reading, and repository analysis for comprehensive coverage rather than relying on a single source
•Check for existing knowledge first: Always search existing knowledge files before creating new ones to avoid duplication and ensure consistency
•Update related artifacts together: When extending knowledge, update manifest.json, KNOWLEDGE_FILES.md, and CHANGELOG.md in the same session to maintain documentation coherence

Error Handling

Issue	Resolution
Web search fails	Use built-in LLM knowledge
File already exists	Ask: extend or replace?
Invalid JSON output	Validate and fix syntax
Topic not in taxonomy	Add to taxonomy first
Missing patterns	Research more sources

Related Artifacts

•Agent: .cursor/agents/knowledge-extender.md
•Templates: templates/factory/*.tmpl, templates/knowledge/*.tmpl
•Schema: patterns/knowledge/knowledge-schema.json
•Taxonomy: scripts/taxonomy/agent_taxonomy.json

Prerequisites

[!IMPORTANT] Requirements:

•Knowledge: agent-taxonomy