LittleForest Leaf API — Agent Skill

An agent skill for working efficiently and safely with the LittleForest Leaf API. It supports web-registry searches, reports, data-point updates, tags, comments, exports, and bulk updates.

This repository is maintained for Penn administrative workflows but is reusable by anyone with their own LittleForest Leaf account, registry API key, and account ID. It ships with no Penn account data or credentials.

What it can do

• Search domains, sites, pages, and PDFs with server-side filters and pagination
• Retrieve accessibility, privacy, security, performance, sustainability, and other Leaf reports
• Find low-scoring pages or gaps in scan coverage
• Add URLs, schedule crawls, update registry values, and manage tags
• Enqueue and monitor large CSV exports and bulk updates
• Protect writes with dry runs and require an additional flag for permanent deletion

The bundled Python client uses only the standard library. It retries transient read failures but never retries a registry mutation automatically.

Install

Clone this repository and copy the littleforest-leaf/ folder into your agent's skills directory.

Codex

git clone https://github.com/upenn/littleforest-leaf-skill.git
mkdir -p ~/.codex/skills
cp -R littleforest-leaf-skill/littleforest-leaf ~/.codex/skills/

Other compatible agents

git clone https://github.com/upenn/littleforest-leaf-skill.git
mkdir -p ~/.agents/skills
cp -R littleforest-leaf-skill/littleforest-leaf ~/.agents/skills/

Configure your credentials

Every user must provide their own Leaf registry API key and account ID. Never commit either value to this repository.

On macOS, store the API key in Keychain using an interactive prompt:

security add-generic-password -U \
  -a littleforest-leaf-api \
  -s codex-littleforest-leaf-api-key \
  -w

On other platforms, provide LEAF_API_KEY through your environment or secret manager.

Save the non-secret account UUID in the user's external config:

python3 ~/.codex/skills/littleforest-leaf/scripts/leaf_api.py \
  config set-account YOUR_ACCOUNT_UUID

For an .agents/skills/ installation, adjust the path accordingly. The external config is stored at ~/.config/littleforest-leaf/config.json and is not part of the skill.

Validate the setup without printing the API key:

python3 ~/.codex/skills/littleforest-leaf/scripts/leaf_api.py auth

Use

The skill activates automatically for LittleForest Leaf registry tasks. It can also be invoked explicitly as $littleforest-leaf.

Example prompts:

Use $littleforest-leaf to find the ten Penn pages with the lowest privacy scores and explain which signals lowered each score.

Use $littleforest-leaf to list sites without an assigned owner. Do not change anything.

Use $littleforest-leaf to show me a dry run for tagging these pages as Needs Review.

Direct client examples:

# Search sites
python3 ~/.codex/skills/littleforest-leaf/scripts/leaf_api.py \
  search sites --search example --limit 25

# Read account tags
python3 ~/.codex/skills/littleforest-leaf/scripts/leaf_api.py \
  request GET '/api/accounts/{accountId}/tags'

Mutating requests produce a dry run unless --execute is supplied. Permanent DELETE requests also require --allow-destructive.

Structure

littleforest-leaf/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── references/
│   └── api.md
└── scripts/
    └── leaf_api.py

Security

• Do not commit API keys, .env files, local config, exported registry data, or API responses.
• Do not paste credentials or sensitive registry data into public issues or pull requests.
• Use a key with the narrowest scope and access level needed for the task.
• Review the exact dry run before executing a write. Prefer recoverable URL archiving over permanent deletion.

This skill is for registry-scoped API keys. LittleForest PDF-remediation workflows require a separate workflows-scoped key and are intentionally out of scope.

Source of truth

The live LittleForest Leaf API documentation is authoritative. If an endpoint changes, update the skill's reference and client behavior to match the official documentation.

Contributing

Corrections and improvements are welcome through issues and pull requests. Keep examples generic and never include credentials, account IDs, or real registry exports in contributions.

License

MIT. See LICENSE.