Updating Internal Docs
Documentsupdating-internal-docsUpdating Internal Docs is an Agent Skill for documents published in the streamlit/streamlit repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Review internal documentation (*.md files) against the current codebase state and propose updates for outdated or incorrect information.
QUICK START
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/streamlit/streamlit/blob/HEAD/.claude/skills/updating-internal-docs/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/updating-internal-docs, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Updating Internal Documentation
Review internal documentation files against the actual codebase state and propose fixes for outdated, incorrect, or missing information.
When to use
- After significant codebase changes (new features, refactors, tooling updates)
- When documentation drift is suspected
- After updating make targets, folder structure, dependencies, skills, or workflows
- When a PR adds or modifies Streamlit features — check if bundled skills (
lib/streamlit/.agents/skills/) need updates
Key files to check
Priority files (most likely to contain codebase-specific instructions):
**/AGENTS.md- AI agent instructions**/README.md- Package/directory documentation.claude/skills/*/SKILL.md- Skill definitions for Streamlit library development.claude/agents/*.md- Subagent definitionswiki/**/*.md- Developer wikiCONTRIBUTING.md- Contributor guidelib/streamlit/.agents/skills/*/SKILL.md- Bundled skills for Streamlit app development (shipped with the library)lib/streamlit/.agents/skills/*/references/*.md- Reference docs for bundled skills
Files to skip (synced copies, updated separately):
.github/copilot-instructions.md.github/instructions/*.md.cursor/rules/*.mdc
Verification checklist
- Make commands exist and work (
make help) - File and folder paths exist
- Tool/dependency references are valid
- Tool version numbers match config files (see below)
- Testing instructions are correct
- Code examples match actual patterns
- Links resolve (internal and external)
- Skill/agent cross-references use current names
-
.github/workflows/AGENTS.mdreflects actual workflow files -
CONTRIBUTING.mdskill/agent overview matches.claude/skills/*/and.claude/agents/ - Bundled skills (
lib/streamlit/.agents/skills/) reflect current Streamlit API and features
Bundled skills and feature changes
When a PR adds or changes a Streamlit feature (new widget, API change, deprecation, new capability), check if the bundled skills need updates:
- Reference docs in
lib/streamlit/.agents/skills/developing-with-streamlit/references/— update the relevant existing reference to document the new feature or API change
Common triggers for bundled skill updates:
- New
st.*commands or widgets - Parameter changes to existing commands
- Deprecated APIs or patterns (add warnings, remove outdated examples)
- New layout or theming capabilities
- Performance-related changes (caching, fragments)
Quick verification commands
# Check path exists: test -e path && echo ok || echo missing
# Check URL reachable: curl -sI -o /dev/null -w "%{http_code}" <url>
Tool version sources
| Tool | Config file |
|---|---|
| TypeScript, React, Vite, Vitest, ESLint, oxfmt, Emotion | frontend/package.json |
| Yarn | frontend/package.json (packageManager field) |
| Python, Ruff, mypy, pytest | pyproject.toml |
| Node.js | .nvmrc |
Issue types
| Type | Description |
|---|---|
| OUTDATED | Info no longer accurate (old make targets, renamed files) |
| INCORRECT | Factually wrong (wrong paths, invalid commands) |
| VERSION_MISMATCH | Documented version differs from actual |
| MISSING | Important info not documented |
| BROKEN_LINK | Links to non-existent resources |
| INCONSISTENT | Conflicts with other docs |
Workflow
- Enumerate: Find all markdown documentation files
- Verify: Cross-reference documented commands, paths, and examples against the codebase
- Report: Present findings grouped by priority
- Fix: Apply changes after user approval
Presenting findings
List all issues and let the user choose which to fix:
Documentation Review: {SCOPE}
═══════════════════════════════════════════════════════════════
Found {N} issues across {M} files:
1. [OUTDATED] AGENTS.md:42
Current: `make python-check`
Actual: Command renamed to `make python-lint`
2. [INCORRECT] wiki/testing.md:15
Current: Tests in `lib/tests/unit/`
Actual: Path is `lib/tests/streamlit/`
3. [BROKEN_LINK] CONTRIBUTING.md:88
Current: Link to `./docs/setup.md`
Actual: File does not exist
Which issues should I fix?
Recommended: "all"
Options: "1" | "1,2,3" | "all" | "skip 3"
Rules
- Verify before proposing: Always check the codebase before suggesting a fix
- Minimal changes: Only change what's actually wrong
- Test commands: Run commands before documenting them
- Keep style consistent: Match existing documentation style
After completing review
- Present all findings to user
- Get approval before making changes
- Apply fixes incrementally
- Run
/checking-changesto validate
Example summary:
Fixed 3 of 4 issues:
- #1 [OUTDATED]: Updated make command in AGENTS.md
- #2 [INCORRECT]: Fixed test path in wiki/testing.md
- #3 [BROKEN_LINK]: Removed dead link in CONTRIBUTING.md
- #4 [INCONSISTENT]: Skipped - requires manual verification
Files modified:
AGENTS.md | 2 +-
wiki/testing.md | 4 ++--
CONTRIBUTING.md | 1 -