Skip to content

App Framework documentation

Overview

This specification defines how documentation and agent skills should be organized, distributed, and maintained within DataRobot App Framework components. The core principle is that documentation and skills should live closest to the component they describe, enabling offline usage, ensuring consistency, and providing both human and LLM-friendly access to information.

Motivation

Documentation distribution

  • Offline-first—Components must be usable without internet connectivity.
  • Self-contained—Templates and apps should include all necessary documentation.
  • LLM-friendly—Documentation must be structured for both human readers and AI agents.
  • Consistency—Location and format should be standardized across all components.

Skills distribution

  • Component-specific knowledge—The unique capabilities of each component should be discoverable by AI agents.
  • Institutional knowledge—Skills capture patterns and practices that don't exist in LLM training data.
  • Portability—Skills should work across multiple agent frameworks until standards emerge.
  • Reusability—General skills should be shared across the ecosystem.

Documentation structure

File organization

Each component must create documentation files within the template's docs folder, following this convention:

template/
├── docs/
│   ├── react.md                    # Single-file component docs
│   ├── agent/              # Multifile component docs
│   │   ├── README.md
│   │   ├── deployment.md
│   │   └── troubleshooting.md
│   ├── llm.md
│   └── Taskfile.yml               # Documentation compilation tasks
├── .skills/                       # Component skills (see below)
└── ...

Naming convention

Single-file documentation: - Format: docs/<component-name>.md - Example: docs/react.md, docs/llm.md

Multifile documentation:

Must have a README.md in the folder, and may or may not contain additional files.

  • Format: docs/<component-name>/README.md (plus any additional files added to the folder)
  • Example: docs/custom-model/README.md, docs/custom-model/deployment.md

This convention prevents collisions similar to the existing infra/infra and infra/configurations folder structure.

Additionally, it encourages deduplication of repeatable components. Specifically, if you have four agent components with different names, they simply overwrite the docs with the latest version or the most recently updated version. If you need specific instance differences in documentation, use the multifile pattern and use paths like docs/agent/{{ agent_app_name }}.md or docs/agent/{{ agent_template_framework }}.md.

Documentation requirements

All component documentation must be:

  1. Comprehensive—Cover all aspects of the component including:
  2. Purpose and use cases.
  3. Installation and setup.
  4. Configuration options.
  5. Usage examples including, common integrations with other components, features, and platform amenities.
  6. Troubleshooting.

  7. Best practices.

  8. LLM-friendly—To be LLM-consumable, include:

  9. Clear section headers.
  10. Code examples with context.
  11. Explicit prerequisites.
  12. Common patterns and anti-patterns.

  13. Links to related components.

  14. Maintainable—To ensure accuracy, be sure the component documentation is:

  15. Version-controlled alongside component code.
  16. Updated with component changes.
  17. Reviewed as part of a PR process.

Documentation compilation

The base component adds a Taskfile that creates a table of contents by compiling all docs items at the file level. Use descriptive file names for components that have multiple markdown documents.

Skills distribution

See Skills for an overview of the skill system and how to use skills in App Framework applications.

File organization

Each component bundles its skills in a .skills folder within the template:

template/
├── .skills/
│   ├── datarobot-app-framework-cicd/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   └── examples/
│   ├── datarobot-app-framework-react-testing/
│   │   └── SKILL.md
│   └── datarobot-app-framework-fastapi-backend-debugging/
│       └── SKILL.md
├── .claude/
│   └── skills/                    # Symlinks to .skills/*
├── .agents/
│   └── skills/                    # Symlinks to .skills/*
└── docs/

The base component provides the symlinks to .claude/skills and .agents/skills directly, so do not do that in your component.

Naming convention

Skills must follow this naming pattern:

Format: datarobot-app-framework-<component>-<skill>

Examples: - datarobot-app-framework-custom-model-deployment - datarobot-app-framework-streamlit-debugging - datarobot-app-framework-react-testing

Special case—Base component: When the skill is in the base component and applies generally, omit the component name: - datarobot-app-framework-cicd (not datarobot-app-framework-base-cicd) - datarobot-app-framework-configuration

Global skills repository

Skills that are general to all app components must:

  1. Exist in both locations:
  2. af-component-base/.skills/ (for template distribution).

  3. datarobot-oss/datarobot-agent-skills (for global discovery).

  4. Stay synchronized:

  5. Changes to general skills must be propagated to both the component and agent skills repositories.

Note: Consider investigating automation such as git submodules or GitHub Actions to ensure synchronization.

  1. To contribute to the global skills repository, skills additions must:
  2. Pass evaluation tests.
  3. Include comprehensive examples.
  4. Document token costs and context requirements.

Skill quality requirements

All skills must:

  1. Be human-authored—LLM-generated skills are prohibited (see research).
  2. Include comprehensive descriptions—Prompt "when should I use this?" not just "what does this do?".
  3. Provide working examples—Use real code that executes successfully.
  4. Document dependencies—Describe external tools, environment variables, and prerequisites.
  5. Specify context costs—Provide estimated token usage and context window requirements.

Implementation guidelines

For component authors

When creating a new component:

  1. Create docs/<component-name>.md or docs/<component-name>/README.md.
  2. Write comprehensive documentation covering all requirements.
  3. Create .skills/<skill-name>/ for each component-specific capability.
  4. Ensure skill names follow the naming convention.
  5. Add documentation compilation tasks to docs/Taskfile.yml.
  6. Test that symlinks work correctly in .claude/skills/ and .agents/skills/.

See also

  • Components—Available App Framework components.
  • Skills—Overview of the skill system and available skills.
  • Component model—Description of how App Framework components are structured and updated.
  • Design principles—Guiding principles behind App Framework design.