# Add Company Context

> Add and validate information served by MCP search and fetch. Use when adding, updating, moving, or removing company context, documentation, internal-library guidance, data-source instructions, runbooks, or engineering standards in this repository.

- Skill: `jacobragsdale/add-company-context` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jacobragsdale/add-company-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jacobragsdale/add-company-context/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jacobragsdale (https://skillmd.com/u/jacobragsdale)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jacobragsdale/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:

   ```markdown
   ---
   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:

   ```bash
   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:

   ```bash
   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.