How harinee/agent-oss-guardrails works
This repository is a content library for AI-agent guardrails, not an application runtime. Its primary artifact is a set of reusable *.skills.md instruction blocks that teams can copy into agent setups to constrain dependency selection, tool usage, and supply-chain choices.
1. Core purpose
The repo translates OSS/security governance into modular agent instructions. The “product” is the instruction set itself: baseline rules plus optional overlays that tailor behavior to a specific agent, ecosystem, or risk context.
2. Primary content layer: foundational guardrails
skills/foundational/ contains the two core policy starting points:
- oss-selection-baseline.skills.md
- oss-selection-strict.skills.md
These are the base architecture layer for all other combinations.
3. Policy overlays
skills/overlays/ is the main composition mechanism. It splits guardrails into orthogonal dimensions:
- capabilities: what the agent can do
- ecosystems: the package/runtime ecosystem involved
- artifact-types: the kind of dependency or tool being introduced
- contexts: the risk environment or deployment setting
This structure supports assembling only the constraints needed for a given scenario.
4. Capability boundary
The capabilities overlays model the agent’s operational permissions, such as installing packages, opening PRs, running shell commands, or using tools/MCP. This is an important boundary because the repo assumes different guardrails are needed depending on what the agent can actually execute.
5. Ecosystem-specific guidance
skills/overlays/ecosystems/ contains language/package-manager-specific rules for:
- container images
- Java/Maven/Gradle
- npm/Node
- Python/pip
This layer localizes dependency-selection behavior to the relevant ecosystem rather than applying generic advice everywhere.
6. Artifact-type controls
skills/overlays/artifact-types/ focuses on special classes of tools or dependencies, including:
- CI/build tools and GitHub Actions
- MCP servers/connectors
- scanners and security tools
These are treated separately because they can carry elevated trust or execution risk beyond ordinary libraries.
7. Context/risk overlays
skills/overlays/contexts/ captures environment sensitivity:
- production
- prototype/low-risk
- regulated/sensitive
This is the risk-adaptation layer, where the same base policy becomes stricter or more permissive depending on where it will be used.
8. Pre-packaged combinations
packaged/ contains ready-made composite skill sets such as:
- baseline-general.skills.md
- strict-agent-high-autonomy.skills.md
- npm-high-autonomy.skills.md
- python-sensitive-repo.skills.md
These are curated bundles that reduce the need for manual composition across multiple overlay files.
9. Examples as usage reference
examples/ shows how the building blocks are intended to be combined for different agent profiles, such as generic, high-autonomy, and MCP-enabled agents. These examples are the closest thing to “integration tests” for the content architecture.
10. Documentation as selection logic
The docs/ folder explains the decision framework:
- why the repo exists
- how to choose a suitable skill set
- design principles
- mapping to standards
- contribution rules
This documentation is part of the control plane: it guides correct assembly of the instruction sets.
11. How the pieces flow together
Typical usage is:
foundational baseline → one or more overlays → optional packaged preset → consumed by an AI agent or team workflow.
The repo does not enforce this at runtime; it provides the content structure and the decision guidance for assembling it correctly.
12. Architectural boundary
There are no app servers, build pipelines, or external service integrations in this repo. The only “runtime” is the downstream AI agent that consumes these markdown skills. The repo’s boundary is therefore instruction authoring and packaging, not enforcement.
13. Security/governance position
The README explicitly states this repo complements, but does not replace, SCA, SBOMs, code review, license review, vulnerability management, or incident response. That means the architecture is intentionally advisory: it shapes agent behavior, while formal security controls remain external.
14. Repo shape summary
If you are drawing the architecture, model it as a modular policy/content system with four overlay dimensions, a foundational base, packaged presets, and documentation/examples around the edges. The key design feature is composability: one base policy can be specialized without duplicating the entire rule set.
Main entry points: capabilities Capabilities · how-to-choose.md How to choose · README.md README · oss-selection-baseline.skills.md Baseline
Components 27
Foundational policy
Base guardrail instruction sets.
Overlay dimensions
Orthogonal policy modifiers for capabilities, ecosystems, artifact types, and risk context.
- Capabilities · Rules shaped by what the agent is allowed to do.
skills/overlays/capabilities - Ecosystems · Rules specialized by package or runtime ecosystem.
skills/overlays/ecosystems - Artifact types · Rules for elevated-risk dependency and tool classes.
skills/overlays/artifact-types - Contexts · Rules adjusted for environment sensitivity and risk.
skills/overlays/contexts - Install · Agent may install packages.
skills/overlays/capabilities/agent-can-install-packages.skills.md - Tools/MCP · Agent may use tools or MCP.
skills/overlays/capabilities/agent-can-use-tools-or-mcp.skills.md - npm/Node · Node and package-manager specific dependency guidance.
skills/overlays/ecosystems/npm-node.skills.md - Python/pip · Python dependency-selection guidance.
skills/overlays/ecosystems/python-pip.skills.md - MCP servers · Special handling for connectors and MCP servers.
skills/overlays/artifact-types/mcp-servers-connectors.skills.md - Production · Stricter rules for production environments.
skills/overlays/contexts/production.skills.md - Prototype · Looser rules for low-risk or exploratory settings.
skills/overlays/contexts/prototype-low-risk.skills.md
Packaged presets
Curated composite skill sets built from the base and overlays.
- Bundles · Curated composite skill sets built from foundational policy and overlays.
packaged - Baseline general · Common baseline composition for general use.
packaged/baseline-general.skills.md - Strict high-autonomy · Tighter preset for capable agents in higher-risk settings.
packaged/strict-agent-high-autonomy.skills.md - npm high-autonomy · Preset tuned for Node/npm and high-autonomy agents.
packaged/npm-high-autonomy.skills.md - Python sensitive · Preset for Python repos in sensitive contexts.
packaged/python-sensitive-repo.skills.md
Usage reference
Example combinations showing intended assembly patterns.
- Generic example · Reference composition for a general agent profile.
examples/generic-agent.skills.md - High autonomy · Reference composition for agents with broad execution rights.
examples/high-autonomy-agent.skills.md - MCP enabled · Reference composition for agents that can use MCP tools.
examples/mcp-enabled-agent.skills.md
Documentation
Decision logic and governance guidance for selecting skill sets.
- README · Repo purpose, boundary, and composition model.
README.md - Why exists · Explains the motivation and governance gap this repo addresses.
docs/why-this-exists.md - How to choose · Decision framework for assembling the right skill set.
docs/how-to-choose.md - Design principles · Rules for composing and structuring guardrails.
docs/design-principles.md - Standards map · Relates the content to external governance and security standards.
docs/mapping-to-standards.md - Contribution guide · Rules for extending and maintaining the skill library.
docs/contribution-guide.md
Connections 32
- README → Baseline: introduces · Explains the foundational starting point.
- README → Capabilities: frames · Describes the overlay dimensions.
- README → Bundles: points to · Shows curated composite presets.
- Why exists → README: supports · Provides motivation for the repository.
- How to choose → Baseline: starts from · Selection begins with a baseline policy.
- How to choose → Capabilities: adds · Selects capability-specific constraints.
- How to choose → Ecosystems: specializes by · Selects ecosystem-specific constraints.
- How to choose → Artifact types: adds · Selects special artifact controls.
- How to choose → Contexts: adapts to · Selects risk-context constraints.
- Design principles → Baseline: guides · Defines the composition model around the base policy.
- Design principles → Strict: guides · Explains when stricter posture applies.
- Standards map → README: anchors · Relates repo guidance to governance and standards.
- Contribution guide → Capabilities: extends · Shows how to author new overlays consistently.
- Baseline → Strict: variant · Represents a stricter foundational option.
- Capabilities → Install: contains · Capability-specific overlays.
- Capabilities → Tools/MCP: contains · Capability-specific overlays.
- Ecosystems → npm/Node: contains · Ecosystem-specific overlays.
- Ecosystems → Python/pip: contains · Ecosystem-specific overlays.
- Artifact types → MCP servers: contains · High-trust artifact overlays.
- Contexts → Production: contains · Risk-sensitive context overlays.
- Contexts → Prototype: contains · Lower-risk context overlays.
- Baseline → Baseline general: composes into · Base input for a common preset.
- Strict → Strict high-autonomy: composes into · Stricter base for a high-autonomy preset.
- Capabilities → Strict high-autonomy: shapes · Capability posture influences the preset.
- npm/Node → npm high-autonomy: shapes · Ecosystem-specific preset composition.
- Python/pip → Python sensitive: shapes · Ecosystem plus risk-context preset composition.
- Prototype → Generic example: illustrates · Example of low-risk or exploratory composition.
- Tools/MCP → MCP enabled: illustrates · Example requiring tool or MCP access.
- MCP servers → MCP enabled: illustrates · Example using MCP-related artifact guidance.
- Baseline general → Generic example: mirrors · Preset shown by example usage.
- Strict high-autonomy → High autonomy: mirrors · Preset shown by example usage.
- npm high-autonomy → High autonomy: mirrors · Node-focused preset shown in examples.