agentleFS
oldwinteroldwinter/skills/skills-doctor/SKILL.md

skills-doctor

Skill11 starsChanged 14 days agoMITView on GitHub

Use when diagnosing the tools, operator identities, API scopes, resource roles, runtime dependencies, or approvals needed to execute skills, especially when handing a workflow to a teammate.

  • Reads credentials

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read the selected skill, its relevant references, and required external skills.

    line 37
  2. Distinctive:

    Read the target repository's live-safety instructions first.

    line 65
  3. Distinctive:

    Keep current-operator findings separate from the colleague's requirements.

    line 89
  4. Distinctive:

    Use a private, ignored location for saved reports.

    line 95

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skills Doctor

Diagnose prerequisites, not business outcomes. Run under the intended operator's own account. An administrator's successful run does not establish a colleague's readiness.

1. Inventory The Target

Locate this installed skill's bundled runner and select the checkout containing the skills to diagnose:

python3 <installed-skill>/scripts/doctor.py --repo-root <checkout> --all
python3 <installed-skill>/scripts/doctor.py --repo-root <checkout> --skill <name>

The runner uses Python 3.10+ and the standard library. It defaults to the caller's working directory, not its own installation. Discovery uses the first existing .claude/skills, .agents/skills, or .codex/skills directory, falling back to the checkout root. Set repeatable --skills-dir paths to override that scope; use --skills-dir . for a whole skill-library checkout.

Without a catalog, each skill remains unverified. Inline command mentions are candidates, not proof of required tools or permissions. Offline discovery does not run those commands, load .env, inspect credentials, or contact services.

Done: name the selected skills and distinguish observed tool hints from reviewed requirements. Report unresolved dependencies rather than guessing.

2. Review Requirements

Read the selected skill, its relevant references, and required external skills. For each execution branch, identify:

  • Local executables and interpreter/package versions.
  • Operator identity, API scopes, resource roles, and network reachability.
  • External skill packages, agent Web/MCP tools, browser sessions and remote runtimes.
  • The separate human approval needed for actual business operations.

Record the requirements in a target-local catalog using the catalog contract and example. Keep private hosts, employee data, credentials, device paths and live reports in the consuming repository, not in this reusable skill. A narrower branch must reflect the task: onboarding marketing employees need not require host or AWS administration; already-provisioned VPN access need not require VPN administrator rights.

python3 <installed-skill>/scripts/doctor.py --repo-root <checkout> \
  --catalog .skills-doctor.json --validate-catalog
python3 <installed-skill>/scripts/doctor.py --repo-root <checkout> \
  --catalog .skills-doctor.json --skill <name> --profile <branch>

Done: every selected capability has evidence sources, a granting owner, and a repair action. Employee access being provisioned is distinct from the operator permissions needed to provision it.

3. Probe Only The Authorized Scope

Read the target repository's live-safety instructions first. Live checks require an explicitly selected skill, a reviewed catalog, and selected probe families:

python3 <installed-skill>/scripts/doctor.py --repo-root <checkout> \
  --catalog .skills-doctor.json --skill <name> --profile <branch> \
  --live github --github-org <organization>

For exact flags, evidence and limitations, read the diagnostic contract. Available probes cover Lark user scopes, GitLab administrator access/token scope, GitHub organization ownership/token scope, AWS identity, and specific Kubernetes RBAC actions. AWS identity alone does not prove IAM or billing permissions.

Manual capabilities stay unverified. The runner never attempts SSH/sudo/Rails fallbacks, grants, login flows, messages, invitations or deployments.

Done: each capability is verified for its stated evidence, known blocked, or explicitly unverified. Do not execute the business workflow merely to test access.

4. Hand Off

Report the tools, roles, remaining blockers, owners and minimum next actions. Keep current-operator findings separate from the colleague's requirements. Tool installation, logins, credential consent, privilege grants and business operations require their own authorization. Use colleague-owned credentials; administrator token/key/session copying is not a repair.

The default output is Markdown; --format json emits the same diagnostic data. Use a private, ignored location for saved reports. Exit 2 means known blockers or invalid input; exit 3 means unresolved checks; exit 0 is not business approval.

Maintenance

The reusable skill ships the runner, fixed probes, and synthetic tests. Consumer catalogs remain consumer-owned; the public example contains no organization inventory. After changing the runner, run:

python3 -m unittest discover -s <installed-skill>/tests -p 'test_*.py'

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.