Add Company Context

Add company context

Add information as validated Markdown content. Never hardcode topic-specific answers or query branches in the search or fetch tools.

Workflow

1. Identify the content root.

   • Read SKILL_MCP_CONTENT_ROOT from the relevant local or deployment configuration when changing a deployed catalog.
   • Use examples/context/ only for repository examples and retrieval evals.
   • Stop and ask if the requested deployed folder is not available; do not guess which directory is authoritative.

2. Inspect existing documents for identifier, owner, authority, terminology, and topic boundaries. Update the existing authoritative document instead of creating a competing answer.

3. Confirm the canonical source URL and current facts. Do not ingest secrets, credentials, personal data, generated build output, or unreviewed guesses.

4. Create or edit the smallest document that answers one fetchable topic. Preserve an existing id when moving or retitling a document.

5. Write strict frontmatter followed by a non-empty Markdown body:

   ---
   id: data/customer-orders
   title: Customer order data source
   url: https://docs.example.com/data/customer-orders
   summary: Find governed customer order data and choose the supported table.
   metadata:
     owner: Data Platform
     authority: company-standard
     updated: "2026-08-04"
   ---
   
   # Customer order data
   
   The supported source is ...
   

   Use a stable lowercase id made of slash-separated segments and hyphens. Make the title readable, the summary rich in the words users will search, and the URL an absolute HTTP or HTTPS citation. Keep every metadata value a string; quote dates, versions, and numbers in YAML.

6. Keep the body bounded and operational. State scope, supported choices, prerequisites, examples, failure conditions, and escalation paths only when they help answer this topic. Split a page before the 60,000-character limit or when different sections need independent search results, ownership, or canonical URLs.

7. Validate the whole content root:

   uv run skill-mcp-validate /absolute/path/to/company-context
   

   Treat every failure as a catalog-blocking defect. Fix duplicate ids, unknown fields, invalid URLs, unquoted metadata values, malformed YAML, empty bodies, encoding problems, and escaping symlinks.

8. Add or update a query in evals/retrieval.json when the change introduces a new concept, synonym, or likely user phrasing. Keep expected ids ordered from most to least relevant and run:

   uv run pytest tests/test_retrieval_evals.py
   uv run pytest
   uv run pre-commit run --all-files
   

9. Review the fetched text, URL, and metadata—not only the search rank. A document is done when a realistic query finds it and fetch returns enough authoritative context for an agent to act without inventing missing facts.

Guardrails

• Keep information in the configured content folder, not in tool descriptions, server instructions, Python conditionals, or this skill.
• Use metadata for provenance and classification context, not access control. Authentication to the server does not make mixed-audience documents safe.
• Prefer one maintained authority over duplicated prose. Link to adjacent topics rather than copying them.
• Do not broaden a document merely to make one evaluation pass. Improve the summary or body with truthful terminology a user would actually use.
• Change src/skill_mcp/catalog.py only when retrieval or the content contract itself must change; pair such changes with boundary tests and MCP contract tests.