gugaio/project-knowledge-writer

Use this skill when the goal is to persist reusable project knowledge, not when the user only wants an answer in the current turn.

Workflow:

1. Read .kael/skills/project-knowledge-writer/references/schema.md.
2. If needed, read .kael/skills/project-knowledge-writer/references/examples.md.
3. Gather concrete evidence first:
   • file paths
   • code flow
   • endpoint or payload shape
   • uncertainty or conflicts
4. Inspect the current project space with:
   • project_list_documents
   • project_get_document
   • If [project_scope] is present in the turn context, reuse that project=<name> as the default project instead of inferring another one.
   • If [project_document_intent] is present, treat it as the strongest hint about the target .md and whether the user already requested or approved that file.
5. Decide whether to:
   • update PROJECT.md for stable project-level context
   • update an existing thematic document
   • propose creating a new thematic .md only when clearly better than reusing an existing file

Creation policy:

• Do not create a new .md silently.
• Prefer asking the user if a new file is desired before creating it.
• If a new file seems best, confirm briefly with the user when that would not make the flow unnecessarily bureaucratic.
• Use judgment: prefer updating an existing document unless a new thematic file is clearly better.

Required quality bar before project_upsert_document:

• Do not save vague summaries like "Android handles auth here".
• Prefer updating an existing file before creating a new one.
• Only create a new .md when the theme is clearly distinct and likely to recur.
• Include concrete file paths and evidence in the Markdown content whenever the conclusion came from code.
• Keep PROJECT.md for overview, boundaries, key flows and conventions.
• Use thematic files for narrower domains:
  • params.md
  • networking.md
  • playback.md
  • auth.md
  • decisions.md

Preferred document metadata:

• project: stable project/app/domain name
• path: PROJECT.md or a thematic file like params.md
• title: short human label
• description: what this file is for
• tags: compact retrieval hints
• content: Markdown content that future agents can read directly

After writing:

• tell the user what file was updated
• include the project and path
• mention whether the file was reused or created now